zipctl 0.1.0__py3-none-any.whl

zipctl/cli/commands/extract.py

@@ -0,0 +1,262 @@
+"""The ``extract`` command."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Protocol
+
+from zipctl.cli.archive import open_archive
+from zipctl.cli.commands.helpers.command import Subparsers, add_command
+from zipctl.cli.commands.helpers.extract_report import report_extraction, report_plain
+from zipctl.cli.commands.helpers.output_options import (
+    OutputArgs,
+    OutputOptions,
+    add_output_options,
+)
+from zipctl.cli.commands.helpers.passwords.options import (
+    PasswordArgs,
+    PasswordOptions,
+    add_password_options,
+    password_pool,
+)
+from zipctl.cli.commands.helpers.passwords.pool import PasswordPool, PasswordProblem
+from zipctl.cli.commands.helpers.policy_options import (
+    PolicyArgs,
+    add_policy_options,
+    load_policy,
+)
+from zipctl.cli.commands.helpers.progress import (
+    ProgressArgs,
+    ProgressRenderer,
+    add_progress_option,
+    progress_renderer,
+)
+from zipctl.cli.commands.helpers.selection import MEMBER_HELP, select_infos
+from zipctl.cli.context import Context
+from zipctl.cli.errors import (
+    EXIT_FAILURE,
+    EXIT_OK,
+    CliError,
+    UsageError,
+    os_error_text,
+)
+from zipctl.cli.output import printable
+from zipctl.exceptions import BadPassword, BadZipFile, PasswordError, PasswordRequired
+from zipctl.zipfile.exceptions import ExtractionFailure
+from zipctl.zipfile.extract import (
+    ExtractionError,
+    ExtractPolicy,
+    ExtractResult,
+    OverwritePolicy,
+)
+from zipctl.zipfile.file import ZipFile
+from zipctl.zipfile.info import ZipInfo
+
+
+class ExtractArgs(OutputArgs, PasswordArgs, PolicyArgs, ProgressArgs, Protocol):
+    archive: str
+    members: list[str]
+    match: list[str]
+    destination: str | None
+    no_policy: bool
+    dry_run: bool
+    overwrite: str | None
+    no_fsync: bool
+
+
+def _extraction_policy(args: ExtractArgs, ctx: Context) -> ExtractPolicy:
+    policy = load_policy(args, ctx)
+    if args.overwrite is not None:
+        policy = replace(policy, overwrite_policy=OverwritePolicy(args.overwrite))
+    if args.no_fsync:
+        policy = replace(policy, fsync_files=False)
+    if args.dry_run:
+        policy = replace(policy, preview_only=True)
+    return policy
+
+
+def _reject_conflicting_options(args: ExtractArgs) -> None:
+    if not args.no_policy:
+        return
+    used = [
+        flag
+        for flag, value in (
+            ("--policy", args.policy),
+            ("--policy-json", args.policy_json),
+            ("--dry-run", args.dry_run),
+            ("--overwrite", args.overwrite),
+            ("--no-fsync", args.no_fsync),
+        )
+        if value not in (None, False)
+    ]
+    if used:
+        raise UsageError(
+            f"--no-policy cannot be combined with {', '.join(used)}; those options "
+            "configure the policy that --no-policy turns off",
+        )
+
+
+def _password_provider(
+    pool: PasswordPool, zf: ZipFile, renderer: ProgressRenderer | None
+) -> Callable[[ZipInfo], bytes | None]:
+    """A ``pwd=`` callable that finds (or asks for) each member's password."""
+
+    def provide(info: ZipInfo) -> bytes | None:
+        if renderer is not None:
+            renderer.clear()  # keep a prompt from colliding with the status line
+        resolved = pool.resolve(zf, info)
+        if not isinstance(resolved, PasswordProblem):
+            return resolved
+        if resolved is PasswordProblem.CORRUPT:
+            raise BadZipFile(resolved.text)
+        if resolved is PasswordProblem.WRONG:
+            raise BadPassword(resolved.text)
+        raise PasswordRequired(resolved.text)
+
+    return provide
+
+
+def _run_extraction(
+    zf: ZipFile,
+    ctx: Context,
+    pool: PasswordPool,
+    policy: ExtractPolicy | None,
+    members: list[ZipInfo] | None,
+    destination: str,
+    *,
+    progress: bool,
+    quiet: bool,
+) -> ExtractResult | None:
+    """Extract; the result is ``None`` for a plain (no policy) extraction."""
+    result = None
+    with (
+        progress_renderer(ctx.stderr, progress) as renderer,
+        warnings.catch_warnings(record=True) as caught,
+    ):
+        warnings.simplefilter("always")
+        provider = _password_provider(pool, zf, renderer)
+        try:
+            if policy is None:
+                zf.extractall(
+                    destination, members=members, pwd=provider, progress=renderer
+                )
+            else:
+                result = zf.extractall(
+                    destination,
+                    members=members,
+                    pwd=provider,
+                    policy=policy,
+                    progress=renderer,
+                )
+        except ExtractionError as exc:
+            result = exc.result
+        except (
+            ExtractionFailure,
+            PasswordError,
+            BadZipFile,
+            NotImplementedError,
+        ) as exc:
+            raise CliError(f"cannot extract: {printable(str(exc))}") from None
+        except OSError as exc:
+            raise CliError(f"cannot extract: {printable(os_error_text(exc))}") from None
+    # A policy violation is reported with the result; anything else is news.
+    reported: set[str] = {v.message for v in result.violations} if result else set()
+    for warning in caught:
+        text = str(warning.message)
+        if text not in reported and not quiet:
+            ctx.warn(printable(text))
+    return result
+
+
+def cmd_extract(args: ExtractArgs, ctx: Context) -> int:
+    _reject_conflicting_options(args)
+    output = OutputOptions.from_args(args)
+    policy = None if args.no_policy else _extraction_policy(args, ctx)
+    destination = args.destination or os.getcwd()
+    with open_archive(args.archive) as zf:
+        patterns = [*args.members, *args.match]
+        members = select_infos(zf.infolist(), patterns) if patterns else None
+        pool = password_pool(PasswordOptions.from_args(args), ctx)
+        result = _run_extraction(
+            zf,
+            ctx,
+            pool,
+            policy,
+            members,
+            destination,
+            progress=args.progress,
+            quiet=output.quiet,
+        )
+        extracted = len(members) if members is not None else len(zf.infolist())
+    if result is None:
+        report_plain(ctx, args.archive, destination, extracted, output)
+        return EXIT_OK
+    report_extraction(
+        ctx,
+        args.archive,
+        destination,
+        result,
+        output,
+    )
+    return EXIT_FAILURE if result.failed_count > 0 else EXIT_OK
+
+
+def register(subparsers: Subparsers) -> None:
+    parser = add_command(
+        subparsers,
+        "extract",
+        cmd_extract,
+        "extract members, enforcing an extraction policy",
+    )
+    parser.add_argument(
+        "archive", metavar="ARCHIVE", help="the archive to extract from"
+    )
+    parser.add_argument(
+        "members",
+        nargs="*",
+        metavar="MEMBER",
+        help=MEMBER_HELP,
+    )
+    parser.add_argument(
+        "--match",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="same as a MEMBER pattern (repeatable); a pattern that matches "
+        "nothing is an error",
+    )
+    parser.add_argument(
+        "-d",
+        "--destination",
+        metavar="DIR",
+        help="directory to extract into. Default: the current directory",
+    )
+    parser.add_argument(
+        "--no-policy",
+        action="store_true",
+        help="extract with no limits or rules (path traversal is still neutralised)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="assess every member and report, writing nothing",
+    )
+    parser.add_argument(
+        "--overwrite",
+        choices=[choice.value for choice in OverwritePolicy],
+        metavar="MODE",
+        help="what to do when a target already exists: error, skip, replace or "
+        "rename. Default: error",
+    )
+    parser.add_argument(
+        "--no-fsync",
+        action="store_true",
+        help="do not fsync each file (faster, but less durable)",
+    )
+    add_progress_option(parser)
+    add_output_options(parser, verbose_help="list every member", quiet=True)
+    add_policy_options(parser)
+    add_password_options(parser)

zipctl/cli/commands/helpers/__init__.py

@@ -0,0 +1 @@
+"""Code only the commands use: their option parsing, reporting and shared steps."""

zipctl/cli/commands/helpers/collect.py

@@ -0,0 +1,225 @@
+"""Turning the paths given to ``create`` into the entries to add."""
+
+from __future__ import annotations
+
+import os
+import stat
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from zipctl.cli.commands.helpers.selection import glob_matcher
+from zipctl.cli.errors import CliError, os_error_filename, os_error_text
+from zipctl.cli.output import printable
+
+__all__ = ["Collector", "Entry"]
+
+
+@dataclass(frozen=True)
+class Entry:
+    """One thing to add: the file on disk and its name in the archive."""
+
+    source: str
+    arcname: str
+    is_dir: bool
+    link_target: str | None = None  # set for a symbolic link stored as a link
+
+
+def _arcname(given: str) -> str:
+    """The archive name for command-line *given*, or refuse one that escapes."""
+    path = os.path.splitdrive(os.path.normpath(given))[1].lstrip("/\\")
+    if path == ".":
+        return ""
+    if path == ".." or path.startswith(("../", "..\\")):
+        raise CliError(
+            f"{printable(given)}: outside the current directory, so it cannot be "
+            "stored under a safe name (use -C DIR to choose the base directory)"
+        )
+    return path.replace(os.sep, "/")
+
+
+def _stored_name(name: str) -> str:
+    try:
+        name.encode("utf-8")
+    except UnicodeEncodeError:
+        raise CliError(
+            f"cannot store {printable(name)}: the file name is not valid UTF-8"
+        ) from None
+    return name
+
+
+def _unreadable(exc: OSError) -> None:
+    """``os.walk`` would skip a directory it cannot list; a backup must not."""
+    where = printable(os_error_filename(exc) or "")
+    raise CliError(f"cannot read {where}: {os_error_text(exc)}") from None
+
+
+def _join(prefix: str, name: str) -> str:
+    return f"{prefix}/{name}".lstrip("/")
+
+
+def _not_a_file(path: str) -> str | None:
+    """Why *path* cannot be added as a file, or ``None`` when it is a regular one."""
+    try:
+        mode = os.stat(path).st_mode
+    except OSError as exc:
+        broken = isinstance(exc, FileNotFoundError) and os.path.islink(path)
+        return "broken symbolic link" if broken else os_error_text(exc)
+    return None if stat.S_ISREG(mode) else "not a regular file"
+
+
+class Collector:
+    """Walks the command-line paths and lists what to add, and what was skipped."""
+
+    def __init__(
+        self,
+        base: str | None,
+        archive: str,
+        exclude: Sequence[str] = (),
+        symlinks: str = "follow",
+    ) -> None:
+        """*symlinks* is ``follow``, ``store`` or ``skip`` (see ``--symlinks``)."""
+        self.base: str | None = base
+        self.symlinks: str = symlinks
+        try:
+            self._archive_stat: os.stat_result | None = os.stat(archive)
+        except OSError:  # not written yet, so nothing collected can be it
+            self._archive_stat = None
+        self.entries: list[Entry] = []
+        self.skipped: list[tuple[str, str]] = []
+        self._seen: set[str] = set()
+        self._exclude: list[tuple[str, Callable[[str], bool]]] = [
+            (p, glob_matcher(p.rstrip("/") or p)) for p in exclude
+        ]
+        self._used: set[str] = set()
+
+    def unused_excludes(self) -> list[str]:
+        """The ``--exclude`` patterns that matched nothing (likely typos)."""
+        return [p for p, _ in self._exclude if p not in self._used]
+
+    def _excluded(self, arcname: str, is_dir: bool) -> bool:
+        """Whether an exclude pattern names *arcname*.
+
+        A pattern with a ``/`` in it is matched against the whole archive name;
+        one without is matched against the last name only, at any depth.  A
+        directory is also matched as ``name/``, so ``build/**`` leaves out
+        ``build`` itself, as ``zip -x`` and ``tar --exclude`` do.
+        """
+        name = arcname.rstrip("/")
+        last = name.rsplit("/", 1)[-1]
+        excluded = False
+        for pattern, matches in self._exclude:
+            if "/" in pattern.rstrip("/"):
+                hit = matches(name) or (is_dir and matches(name + "/"))
+            else:
+                hit = matches(last)
+            if hit:
+                self._used.add(pattern)
+                excluded = True
+        return excluded
+
+    def _is_archive(self, source: str) -> bool:
+        if self._archive_stat is None:
+            return False
+        try:
+            return os.path.samestat(self._archive_stat, os.stat(source))
+        except OSError:  # vanished or unreadable: reported when it is added
+            return False
+
+    def _add(
+        self,
+        source: str,
+        arcname: str,
+        is_dir: bool,
+        link_target: str | None = None,
+    ) -> None:
+        if link_target is None and self._is_archive(source):
+            self.skipped.append((source, "it is the archive being written"))
+            return
+        key = arcname + "/" if is_dir else arcname
+        if key in self._seen:
+            return
+        self._seen.add(key)
+        self.entries.append(Entry(source, _stored_name(key), is_dir, link_target))
+
+    def _link(self, source: str, arcname: str) -> None:
+        """Handle the symbolic link *source* per ``--symlinks`` (not ``follow``)."""
+        if self.symlinks == "skip":
+            self._skip(source, "symbolic link")
+            return
+        target = os.readlink(source)
+        try:
+            target.encode("utf-8")
+        except UnicodeEncodeError:
+            raise CliError(
+                f"cannot store the link {printable(source)}: its target is not "
+                "valid UTF-8"
+            ) from None
+        self._add(source, arcname, False, target)
+
+    def _skip(self, source: str, reason: str) -> None:
+        self.skipped.append((os.path.normpath(source), reason))
+
+    def add_path(self, given: str) -> None:
+        """Add a path named on the command line; one that cannot be read is fatal."""
+        source = (
+            given
+            if os.path.isabs(given) or not self.base
+            else os.path.join(self.base, given)
+        )
+        arc = _arcname(given)
+        if arc and self._excluded(arc, os.path.isdir(source)):
+            return
+        if self.symlinks != "follow" and os.path.islink(source):
+            self._link(source, arc or os.path.basename(source))
+            return
+        try:
+            mode = os.stat(source).st_mode
+        except OSError as exc:
+            raise CliError(
+                f"cannot read {printable(given)}: {os_error_text(exc)}"
+            ) from None
+        if stat.S_ISDIR(mode):
+            self._walk(source, arc)
+        elif stat.S_ISREG(mode):
+            self._add(source, arc or os.path.basename(source), False)
+        else:
+            raise CliError(f"{printable(given)}: not a regular file or directory")
+
+    def _walk(self, top: str, arc: str) -> None:
+        """Add what is under *top*; what cannot be read is skipped with a reason."""
+        if arc:
+            self._add(top, arc, True)
+        for root, dirs, files in os.walk(top, onerror=_unreadable):
+            dirs.sort()
+            files.sort()
+            here = os.path.relpath(root, top)
+            prefix = arc if here == "." else f"{arc}/{here}".lstrip("/")
+            prefix = prefix.replace(os.sep, "/")
+            self._walk_dirs(root, dirs, prefix)
+            for name in files:
+                path = os.path.join(root, name)
+                arcname = _join(prefix, name)
+                if self._excluded(arcname, False):
+                    continue
+                if self.symlinks != "follow" and os.path.islink(path):
+                    self._link(path, arcname)
+                elif reason := _not_a_file(path):
+                    self._skip(path, reason)
+                else:
+                    self._add(path, arcname, False)
+
+    def _walk_dirs(self, root: str, dirs: list[str], prefix: str) -> None:
+        """Add the directories of one level; *dirs* keeps those to descend into."""
+        for name in list(dirs):
+            path = os.path.join(root, name)
+            arcname = _join(prefix, name)
+            if self._excluded(arcname, True):
+                dirs.remove(name)
+            elif os.path.islink(path):
+                dirs.remove(name)
+                if self.symlinks == "store":
+                    self._link(path, arcname)
+                else:
+                    self._skip(path, "symbolic link to a directory")
+            else:
+                self._add(path, arcname, True)

zipctl/cli/commands/helpers/command.py

@@ -0,0 +1,119 @@
+"""How a subcommand is added to the parser."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable, Sequence
+from difflib import get_close_matches
+from typing import TYPE_CHECKING, TypeVar, cast
+
+from typing_extensions import override
+
+from zipctl.cli.context import Context
+from zipctl.cli.formatter import HelpFormatter
+
+__all__ = ["CommandsAction", "Handler", "Subparsers", "add_command", "add_subcommands"]
+
+_Args = TypeVar("_Args")
+
+Handler = Callable[[argparse.Namespace, Context], int]
+
+# argparse's subparsers action is generic only for type checkers
+if TYPE_CHECKING:
+    Subparsers = argparse._SubParsersAction[argparse.ArgumentParser]  # pyright: ignore[reportPrivateUsage]
+else:
+    Subparsers = argparse._SubParsersAction
+
+
+def add_command(
+    subparsers: Subparsers,
+    name: str,
+    handler: Callable[[_Args, Context], int] | None,
+    help_text: str,
+    description: str | None = None,
+) -> argparse.ArgumentParser:
+    """Add subcommand *name* running *handler* to *subparsers*.
+
+    *handler* is ``None`` for a command that only groups further subcommands.
+    Its *_Args* is the shape of the options the command adds: the namespace
+    argparse builds is cast to it, the one place that trusts the parser.
+    """
+    parser: argparse.ArgumentParser = subparsers.add_parser(
+        name,
+        help=help_text,
+        description=description or help_text,
+        allow_abbrev=False,
+        formatter_class=HelpFormatter,
+    )
+    if handler is not None:
+
+        def run(args: argparse.Namespace, ctx: Context) -> int:
+            return handler(cast("_Args", args), ctx)
+
+        parser.set_defaults(handler=run)
+    return parser
+
+
+class CommandsAction(Subparsers):
+    """The command choice, suggesting the nearest command for a mistyped one."""
+
+    def __init__(
+        self,
+        option_strings: Sequence[str],
+        prog: str,
+        parser_class: type[argparse.ArgumentParser],
+        dest: str = argparse.SUPPRESS,
+        required: bool = False,
+        help: str | None = None,  # noqa: A002  # mirrors argparse.Action
+        metavar: str | tuple[str, ...] | None = None,
+    ) -> None:
+        super().__init__(
+            option_strings, prog, parser_class, dest, required, help, metavar
+        )
+        # argparse would reject an unknown name before __call__ gets to suggest one
+        self.choices = None  # type: ignore[assignment]  # ty: ignore[invalid-assignment]  # pyright: ignore[reportAttributeAccessIssue, reportUnannotatedClassAttribute]
+
+    @override
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: str | Sequence[str] | None,
+        option_string: str | None = None,
+    ) -> None:
+        assert values is not None
+        assert not isinstance(values, str)
+        name = str(values[0])
+        if name not in self._name_parser_map:
+            lines = [f"unknown command {name!r}"]
+            for close in get_close_matches(name, self._name_parser_map, n=1):
+                lines.append(f"  Did you mean {close!r}?")
+            lines.append(f"  Run '{parser.prog} --help' to see all commands.")
+            parser.error("\n".join(lines))
+        super().__call__(parser, namespace, values, option_string)
+        # argparse reports these at the top; the command's own usage is more useful
+        extras: list[str] | None = getattr(
+            namespace,
+            argparse._UNRECOGNIZED_ARGS_ATTR,  # pyright: ignore[reportPrivateUsage]
+            None,
+        )
+        if extras:
+            sub = self._name_parser_map[name]
+            sub.error(
+                f"unrecognized arguments: {' '.join(extras)}\n"
+                f"  Run '{sub.prog} --help' to see all options."
+            )
+
+
+def add_subcommands(parser: argparse.ArgumentParser, dest: str) -> Subparsers:
+    """Give *parser* a ``Commands`` section listing the subcommands added to it."""
+    subparsers = parser.add_subparsers(
+        action=CommandsAction,
+        title="Commands",
+        dest=dest,
+        metavar="COMMAND",
+        required=True,
+    )
+    groups = parser._action_groups
+    groups.insert(1, groups.pop())  # "Commands" before "Options"
+    return subparsers

zipctl/cli/commands/helpers/copying/__init__.py

@@ -0,0 +1 @@
+"""How the copying commands (encrypt, decrypt, rewrite) copy an archive."""