feat(cli): redesign the commands and flags, add entry filters, --rm, --dereference and a 'test' command

bench/run.py

@@ -26,7 +26,8 @@
 from tabulate import tabulate
 
 from compresso import _core
-from compresso.introspect.benchmark import BenchmarkResult, print_results
+from compresso.cli._render.benchmark import benchmark_results
+from compresso.introspect.benchmark import BenchmarkResult
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 WORK_DIR = REPO_ROOT / "build" / "bench"
@@ -326,7 +327,7 @@ def main() -> None:
     args = parser.parse_args()
 
     results = run(args.formats.split(","), args.size_mb, args.repeats, args.cool)
-    print_results(results)
+    benchmark_results(results)
 
     if args.compare:
         compare(results, args.compare)

pyproject.toml

@@ -35,7 +35,6 @@ dev = [
 
 [project.scripts]
 compresso = "compresso.cli:main"
-comp = "compresso.cli:main"
 
 [tool.meson-python.args]
 # Meson only activates MSVC when no other compiler is on PATH, which the MinGW

src/compresso/__init__.py

@@ -9,6 +9,7 @@
     ExtractionPolicyError,
     HeaderError,
     IncompleteExtractionError,
+    SourceRemovalError,
     TrailingDataWarning,
     compress_file,
     decompress_file,
@@ -20,8 +21,12 @@
     CompressionPlan,
     DecompressionJob,
     DecompressionPlan,
+    Strategy,
+    VerificationJob,
+    VerificationPlan,
     plan_compression,
     plan_decompression,
+    plan_verification,
 )
 from .frontend.archive_api import (
     ArchiveEntry,
@@ -36,7 +41,7 @@
     plan_archive,
     plan_extraction,
 )
-from .introspect.benchmark import benchmark_file, print_results
+from .introspect.benchmark import benchmark_file
 from .introspect.capabilities import list_capabilities
 from .introspect.file_inspect import InspectResult, inspect
 from .introspect.speeds import get_estimated_speeds
@@ -67,8 +72,12 @@
     "JobResult",
     "OverwriteMode",
     "ProgressCallback",
+    "SourceRemovalError",
+    "Strategy",
     "SymlinkMode",
     "TrailingDataWarning",
+    "VerificationJob",
+    "VerificationPlan",
     "benchmark_file",
     "compress_file",
     "decompress_file",
@@ -79,5 +88,5 @@
     "plan_compression",
     "plan_decompression",
     "plan_extraction",
-    "print_results",
+    "plan_verification",
 ]

src/compresso/_core.pyi

@@ -27,6 +27,19 @@ class IncompleteExtractionError(Error):
     Raises on completion, anything extracted is kept.
     """
 
+class SourceRemovalError(Error):
+    """An archive was written, but some of its sources could not be deleted.
+
+    The archive is complete, and every other source is deleted.
+
+    Attributes:
+        output: The path the archive was written to.
+        failures: Each path left behind, with the reason.
+    """
+
+    output: str
+    failures: list[tuple[str, str]]
+
 class CorruptDataError(Error):
     """The input is corrupt, truncated, or not the format it claims to be."""
 
@@ -153,14 +166,27 @@ def create_archive(
     threads: int = ...,
     progress: ProgressFn | None = ...,
     cancel: CancelToken | None = ...,
+    include: Sequence[str] = ...,
+    exclude: Sequence[str] = ...,
+    remove_sources: bool = ...,
+    dereference: bool = ...,
 ) -> str:
     """Create an archive from the given input paths in the given format.
 
     `overwrite` is 0 = error (default), 1 = skip, 2 = overwrite, 3 = rename;
-    applied to the single destination archive.
+    applied to the single destination archive; `remove_sources` with skip
+    raises ValueError.
 
     Returns the path actually written, which RENAME may have changed from
     `output_path`; SKIP returns `output_path` unchanged and writes nothing.
+
+    `include` and `exclude` are globs matched against entry names; an exclude
+    wins and isn't descended into, and with any includes, only matching entries
+    and the directories holding them are stored.
+
+    `dereference` stores what symlinks lead to; one that's dangling, or that
+    leads to a directory above it, stays a link; `remove_sources` then deletes
+    the links, and not their targets.
     """
 
 def extract_archive(
@@ -179,6 +205,8 @@ def extract_archive(
     threads: int = ...,
     progress: ProgressFn | None = ...,
     cancel: CancelToken | None = ...,
+    include: Sequence[str] = ...,
+    exclude: Sequence[str] = ...,
 ) -> None:
     """Extract an archive to output_dir; an empty `files` extracts every entry.
 
@@ -187,12 +215,31 @@ def extract_archive(
 
     `overwrite` is 0 = error, 1 = skip, 2 = overwrite, 3 = rename;
     `allow_symlinks` is 0 = deny, 1 = allow if the target stays inside
-    output_dir, 2 = rewrite to regular files, -1 = the format's default (2 for zip, 0 otherwise);
-    `max_total_size` and `max_depth` treat 0 as unlimited;
+    output_dir, 2 = rewrite to regular files, -1 = the format's default (2 for zip,
+    0 otherwise); `max_total_size` and `max_depth` treat 0 as unlimited;
     `overwrite_dir_metadata` also restores the mode and mtime of a directory
     that already exists, as GNU tar does, except when `overwrite` is 1 (skip);
     `exact_permissions` restores modes verbatim, where by default
     setuid/setgid/sticky are dropped and the umask applies.
+
+    `include` and `exclude` are matched as for `create_archive`: as in bsdtar,
+    an entry is extracted if `files` names it or an include matches it, and an
+    exclude overrides both; a directory entry is kept only if it matches
+    itself; an include that no entry matches raises `IncompleteExtractionError`,
+    as a name in `files` does, after the rest is extracted.
+    """
+
+def verify_file(
+    path: StrOrBytesPath,
+    *,
+    threads: int = ...,
+    progress: ProgressFn | None = ...,
+    cancel: CancelToken | None = ...,
+) -> None:
+    """Decode all of an archive or compressed file, writing nothing.
+
+    Raises what extracting it would for damaged data, so it proves only what
+    the format checks: a plain tar's file data carries no checksum.
     """
 
 def detect_format(file_path: StrOrBytesPath) -> str:
@@ -204,9 +251,22 @@ def gzip_stored_name(file_path: StrOrBytesPath) -> bytes | None:
     Always None for a non-gzip file.
     """
 
+def stored_content_size(file_path: StrOrBytesPath) -> int | None:
+    """Return the uncompressed size an xz, zstd, lz4 or snappy file states, or None.
+
+    Reads no compressed data, so a damaged file can still state a size; None for
+    any other format, a zstd or lz4 frame written from a stream, or trailing data.
+    """
+
 def format_is_archive(format: str) -> bool:
     """Return whether a format's container can hold more than one entry."""
 
+def format_stores_hardlinks(format: str) -> bool:
+    """Return whether an archive format stores a file's later names as links."""
+
+def path_matches(path: str, patterns: Sequence[str]) -> bool:
+    """Return whether any glob matches an entry path, as `include` and `exclude` do."""
+
 class _StandaloneFormatDict(TypedDict):
     """One single file container format, as defined by `standalone_formats`."""
 

src/compresso/cli/__init__.py

@@ -2,7 +2,13 @@
 
 from __future__ import annotations
 
-from . import algos, benchmark, compress, extract, inspect
+import io
+import re
+import sys
+from typing import Any, TextIO
+
+from . import benchmark, compress, extract, formats, info, verify
+from . import list as list_
 from ._app import app
 
 __all__ = ["app", "main"]
@@ -11,18 +17,92 @@
 _COMMAND_MODULES = (
     compress,
     extract,
-    inspect,
+    verify,
+    list_,
+    info,
+    formats,
     benchmark,
-    algos,
 )
 
 for _module in _COMMAND_MODULES:
     _module.register()
 
 
+# Styling and spaces, so Rich's padded blank lines count as blank
+_INVISIBLE = re.compile(r"\x1b\[[0-9;]*m| ")
+
+
+class _Padded:
+    """A terminal stream that gives a run's output one blank line above it.
+
+    main() adds the one below. Output that already starts or ends with a blank
+    line, as `--help` does, gets no extra.
+    """
+
+    # Shared, so stdout and stderr pad once between them
+    tail: str | None = None  # the last two visible characters written
+    last: _Padded | None = None
+
+    def __init__(self, stream: TextIO) -> None:
+        """Initialise a padded stream.
+
+        Args:
+            stream: The underlying stream to write to.
+        """
+        self._stream = stream
+
+    def write(self, data: str) -> int:
+        """Write to the underlying stream, with a blank line above if needed.
+
+        Args:
+            data: The string to write.
+
+        Returns:
+            The number of characters written.
+        """
+        # Typer/Click probes for a binary stream with write(b"")
+        visible = _INVISIBLE.sub("", data) if isinstance(data, str) else ""
+        if visible:
+            if _Padded.tail is None and not visible.startswith("\n"):
+                self._stream.write("\n")
+
+            _Padded.tail = ((_Padded.tail or "") + visible)[-2:]
+            _Padded.last = self
+
+        return self._stream.write(data)
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the underlying stream.
+
+        Args:
+            name: The name of the attribute to access.
+
+        Returns:
+            The value of the requested attribute.
+        """
+        return getattr(self._stream, name)
+
+
 def main() -> None:
     """Entry point for the CLI."""
-    app()
+    # A pipe on Windows takes the locale code page, which can't encode markers
+    # like '→'; escape rather than raise
+    if isinstance(sys.stdout, io.TextIOWrapper):
+        sys.stdout.reconfigure(errors="backslashreplace")
+
+    # Not when piped, as tar and gzip don't pad what a script reads
+    if sys.stdout.isatty():
+        sys.stdout = _Padded(sys.stdout)
+
+    if sys.stderr.isatty():
+        sys.stderr = _Padded(sys.stderr)
+
+    try:
+        app()
+
+    finally:
+        if _Padded.last and _Padded.tail != "\n\n":
+            _Padded.last.write("\n")
 
 
 if __name__ == "__main__":