boto3-s3-cli 0.1.0__py3-none-any.whl

boto3_s3_cli/__init__.py

@@ -0,0 +1,26 @@
+"""boto3-s3-cli - `aws s3` compatible CLI built on the boto3-s3 library."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    __version__: str
+
+__all__ = ["__version__"]
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve ``__version__`` on first access (PEP 562).
+
+    importlib.metadata costs ~20ms to import; deferring it keeps that off
+    every CLI start (import contract, docs/imports.md).
+    """
+    if name == "__version__":
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            value = version("boto3-s3-cli")
+        except PackageNotFoundError:  # pragma: no cover - only from an unbuilt checkout
+            value = "0.0.0+unknown"
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

boto3_s3_cli/autoprompt/__init__.py

@@ -0,0 +1,19 @@
+"""Auto-prompt (``--cli-auto-prompt``) support: an interactive prompt with
+``aws s3``-faithful completion, active only when ``prompt_toolkit`` is installed.
+
+This package is imported lazily - only once ``--cli-auto-prompt`` actually fires
+on an install that has the ``autoprompt`` extra (``prompt_toolkit``). Nothing
+here is touched on the ``--help`` / ``--version`` / usage / normal-dispatch
+paths (import contract, ``docs/imports.md``).
+
+The completion engine (:mod:`model`, :mod:`parser`, :mod:`completers`) is a
+port of aws-cli's ``awscli/autocomplete/`` scoped to the ``boto3-s3`` command
+surface, and is pure Python (no ``prompt_toolkit``). Only :mod:`prompt` binds
+``prompt_toolkit``. Design: ``docs/autoprompt.md``.
+"""
+
+from __future__ import annotations
+
+from boto3_s3_cli.autoprompt.prompter import AutoPrompter
+
+__all__ = ["AutoPrompter"]

boto3_s3_cli/autoprompt/completers.py

@@ -0,0 +1,336 @@
+"""The completers and the filter/combiner - a port of aws-cli's completion core.
+
+Ports ``CompletionResult`` / ``AutoCompleter`` (``completer.py``),
+``fuzzy_filter`` (``filters.py``), and the completers from
+``autocomplete/local/basic.py``, scoped to what ``aws s3`` actually exercises:
+
+- :class:`ModelIndexCompleter` - subcommand names and option names.
+- :class:`RegionCompleter` / :class:`ProfileCompleter` - ``--region`` /
+  ``--profile`` values (local botocore/config data).
+- :class:`FilePathCompleter` - ``file://`` / ``fileb://`` paths.
+- :class:`ChoicesCompleter` - values for any option with fixed ``choices``.
+
+The auto-prompt UI is charter-exempt (``docs/autoprompt.md`` section 1), so these
+completers favor *usability* over a byte-faithful port. :class:`ChoicesCompleter`
+completes every choice-bearing option uniformly from the argparse model, where
+aws only completes *global* choices (its command-level path reads
+``argument_model.enum``, empty for the ``s3`` customization args whose values
+live on ``.choices``) - so ``--storage-class`` etc. complete here but not in aws.
+Reachability is widened the same way by the parser tuning (``parser.py``): option
+values complete before any positional, and options keep completing after a
+command's second positional path.
+
+Pure Python - botocore is imported lazily, only when a region/profile value is
+actually being completed (the interactive path), never on a parse path.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NamedTuple
+
+from boto3_s3_cli.autoprompt.model import ROOT
+
+if TYPE_CHECKING:
+    from boto3_s3_cli.autoprompt.model import CompletionModel
+    from boto3_s3_cli.autoprompt.parser import CLIParser, ParsedResult
+
+
+@dataclass
+class CompletionResult:
+    """One completion candidate plus the metadata the prompt UI renders.
+
+    Mirrors aws-cli's ``CompletionResult``: ``name`` is inserted, ``display_text``
+    overrides the menu label, ``cli_type_name`` / ``help_text`` feed the
+    ``display_meta`` line, ``required`` drives required-first ordering.
+    """
+
+    name: str
+    starting_index: int = 0
+    required: bool = False
+    cli_type_name: str = ""
+    help_text: str | None = None
+    display_text: str | None = None
+
+
+# A response filter narrows + ranks candidates against the current fragment;
+# auto-prompt uses fuzzy_filter, the default elsewhere is startswith_filter.
+ResponseFilter = Callable[[str, "list[CompletionResult]"], "list[CompletionResult]"]
+# A value provider sources region/profile candidates; injecting a fake keeps the
+# unit tests free of botocore and the network.
+ValueProvider = Callable[[], Iterable[str]]
+
+
+class _FuzzyMatch(NamedTuple):
+    match_length: int
+    start_pos: int
+    completion: CompletionResult
+
+
+def fuzzy_filter(prefix: str, completions: list[CompletionResult]) -> list[CompletionResult]:
+    """Subsequence match + rank, exactly as aws-cli's auto-prompt filter.
+
+    ``"rmt"`` becomes ``/r.*?m.*?t/``; each candidate keeps its shortest,
+    left-most match, and results sort by (match length, start, display, name).
+    """
+    if prefix and completions:
+        fuzzy_matches: list[_FuzzyMatch] = []
+        pattern = ".*?".join(map(re.escape, prefix))
+        pattern = f"(?=({pattern}))"
+        regex = re.compile(pattern, re.IGNORECASE)
+        for completion in completions:
+            name = completion.display_text or completion.name
+            matches = list(regex.finditer(name))
+            if matches:
+                best = min(matches, key=lambda m: (m.start(), len(m.group(1))))
+                fuzzy_matches.append(_FuzzyMatch(len(best.group(1)), best.start(), completion))
+        return [
+            match.completion
+            for match in sorted(
+                fuzzy_matches,
+                key=lambda m: (
+                    m.match_length,
+                    m.start_pos,
+                    m.completion.display_text or "",
+                    m.completion.name,
+                ),
+            )
+        ]
+    return completions
+
+
+def startswith_filter(prefix: str, completions: list[CompletionResult]) -> list[CompletionResult]:
+    return [c for c in completions if (c.display_text or c.name).startswith(prefix)]
+
+
+def _clean_help(text: str | None) -> str | None:
+    if not text:
+        return None
+    return re.sub("<.*?>", "", text).replace("\n", " ")
+
+
+class BaseCompleter:
+    """Return ``None`` to defer to the next completer, or a (possibly empty) list."""
+
+    def complete(self, parsed: ParsedResult) -> list[CompletionResult] | None:
+        raise NotImplementedError("complete")
+
+
+class AutoCompleter:
+    """Runs completers in order; the first non-``None`` result wins (aws-faithful)."""
+
+    def __init__(self, parser: CLIParser, completers: list[BaseCompleter]) -> None:
+        self._parser = parser
+        self._completers = completers
+
+    def autocomplete(self, command_line: str, index: int | None = None) -> list[CompletionResult]:
+        parsed = self._parser.parse(command_line, index)
+        for completer in self._completers:
+            result = completer.complete(parsed)
+            if result is not None:
+                return result
+        return []
+
+
+class ModelIndexCompleter(BaseCompleter):
+    """Completes subcommand names and option names from the model."""
+
+    def __init__(self, model: CompletionModel, response_filter: ResponseFilter) -> None:
+        self._index = model
+        self._filter = response_filter
+
+    def complete(self, parsed: ParsedResult) -> list[CompletionResult] | None:
+        are_unparsed_items_paths = [
+            bool(re.search(r"[./\\:]|(--)", item)) for item in parsed.unparsed_items
+        ]
+        if parsed.unparsed_items and all(are_unparsed_items_paths) and not parsed.current_param:
+            # cp/mv/sync take two positional paths but the model has one slot, so
+            # the second path lands in unparsed_items. Offer the option set: an
+            # empty trailing fragment shows the whole set, a `--frag` narrows it.
+            # (The faithful port used the command name as the prefix here, which
+            # fuzzy-filtered the options down to a useless subset; we favor
+            # usability - the auto-prompt UI is charter-exempt, docs/autoprompt.md
+            # section 2.) When current_param is set we are typing an option *value*, so
+            # we fall through to the value completers below instead.
+            fragment = parsed.current_fragment or ""
+            prefix = "" if fragment == "--" else fragment
+            return self._filter(prefix, self._complete_options(parsed))
+        elif parsed.unparsed_items or parsed.current_fragment is None or parsed.current_param:
+            # Unknown tokens, nothing being typed, or we're on an option value:
+            # defer (value completers handle the last case).
+            return None
+        current_fragment = parsed.current_fragment
+        if current_fragment.startswith("--"):
+            prefix = "" if current_fragment == "--" else current_fragment
+            return self._filter(prefix, self._complete_options(parsed))
+        commands = self._complete_command(parsed)
+        if not commands:
+            return self._filter(current_fragment, self._complete_options(parsed))
+        return self._filter(current_fragment, commands)
+
+    def _complete_command(self, parsed: ParsedResult) -> list[CompletionResult]:
+        lineage = parsed.lineage + ([parsed.current_command] if parsed.current_command else [])
+        offset = -len(parsed.current_fragment or "")
+        return [
+            CompletionResult(name, help_text=full_name, starting_index=offset)
+            for name, full_name in self._index.commands_with_full_name(lineage)
+        ]
+
+    def _complete_options(self, parsed: ParsedResult) -> list[CompletionResult]:
+        offset = -len(parsed.current_fragment or "")
+        is_in_global_scope = parsed.lineage == [] and parsed.current_command == ROOT
+        results: list[CompletionResult] = []
+        if not is_in_global_scope:
+            for arg_name in self._index.arg_names(
+                lineage=parsed.lineage, command_name=parsed.current_command
+            ):
+                arg = self._index.get_argument_data(
+                    parsed.lineage, parsed.current_command, arg_name
+                )
+                if arg is None:
+                    continue
+                results.append(
+                    CompletionResult(
+                        f"--{arg_name}",
+                        starting_index=offset,
+                        required=arg.required,
+                        cli_type_name=arg.type_name,
+                        help_text=_clean_help(arg.help_text),
+                    )
+                )
+        for arg in self._index.global_arg_data():
+            results.append(
+                CompletionResult(
+                    f"--{arg.name}",
+                    starting_index=offset,
+                    required=False,
+                    cli_type_name=arg.type_name,
+                    help_text=_clean_help(arg.help_text),
+                )
+            )
+        supplied = list(parsed.parsed_params) + list(parsed.global_params)
+        return [r for r in results if r.name.strip("-") not in supplied]
+
+
+class RegionCompleter(BaseCompleter):
+    """Completes ``--region`` values from local botocore endpoint data (no network)."""
+
+    def __init__(
+        self, response_filter: ResponseFilter, regions_provider: ValueProvider | None = None
+    ) -> None:
+        self._filter = response_filter
+        self._regions_provider = regions_provider
+        self._cache: list[str] | None = None
+
+    def complete(self, parsed: ParsedResult) -> list[CompletionResult] | None:
+        if parsed.current_param == "region" and parsed.current_fragment is not None:
+            results = [CompletionResult(name=r) for r in self._regions()]
+            return self._filter(parsed.current_fragment, results)
+        return None
+
+    def _regions(self) -> list[str]:
+        # Cached for the completer's lifetime (one interactive prompt session):
+        # value completion fires on every keystroke, and a fresh
+        # boto3.Session().get_available_regions() costs ~40 ms each (vs ~3 ms once
+        # resolved). aws caches the session for the same reason (it reuses one
+        # botocore Session across completions - autocomplete/local/basic.py).
+        if self._cache is None:
+            if self._regions_provider is not None:
+                self._cache = list(self._regions_provider())
+            else:
+                import boto3  # lazy: only on an actual --region completion
+
+                # We are an S3-only CLI, so always resolve S3's regions (aws keys
+                # off the service in the command lineage, which for us is always s3).
+                self._cache = boto3.Session().get_available_regions("s3")
+        return self._cache
+
+
+class ProfileCompleter(BaseCompleter):
+    """Completes ``--profile`` values from the local AWS config (no network)."""
+
+    def __init__(
+        self, response_filter: ResponseFilter, profiles_provider: ValueProvider | None = None
+    ) -> None:
+        self._filter = response_filter
+        self._profiles_provider = profiles_provider
+        self._cache: list[str] | None = None
+
+    def complete(self, parsed: ParsedResult) -> list[CompletionResult] | None:
+        if parsed.current_param == "profile" and parsed.current_fragment is not None:
+            results = [CompletionResult(name=p) for p in self._profiles()]
+            return self._filter(parsed.current_fragment, results)
+        return None
+
+    def _profiles(self) -> list[str]:
+        # Cached for the prompt session, like the regions above (aws-faithful).
+        if self._cache is None:
+            if self._profiles_provider is not None:
+                self._cache = list(self._profiles_provider())
+            else:
+                import boto3  # lazy: only on an actual --profile completion
+
+                self._cache = boto3.Session().available_profiles
+        return self._cache
+
+
+class FilePathCompleter(BaseCompleter):
+    """Completes local paths once the fragment starts with ``file://``/``fileb://``.
+
+    aws drives this with ``prompt_toolkit``'s ``PathCompleter``; we reimplement
+    the directory listing in pure Python so the completion engine carries no
+    ``prompt_toolkit`` dependency (only :mod:`prompt` binds it).
+    """
+
+    _PREFIXES = ("file://", "fileb://")
+
+    def __init__(self, response_filter: ResponseFilter) -> None:
+        self._filter = response_filter
+
+    def complete(self, parsed: ParsedResult) -> list[CompletionResult] | None:
+        fragment = parsed.current_fragment
+        if not fragment or not fragment.startswith(self._PREFIXES):
+            return None
+        prefix = next(p for p in self._PREFIXES if fragment.startswith(p))
+        filename_part = fragment[len(prefix) :]
+        if filename_part == "~":
+            return [CompletionResult(f"{prefix}~{os.sep}")]
+        dirname = os.path.dirname(filename_part)
+        listing_dir = os.path.expanduser(dirname) if dirname else os.curdir
+        try:
+            entries = sorted(os.listdir(listing_dir))
+        except OSError:
+            return []
+        display_dir = f"{dirname}{os.sep}" if dirname and dirname != os.sep else dirname
+        results: list[CompletionResult] = []
+        for entry in entries:
+            display = entry + (os.sep if os.path.isdir(os.path.join(listing_dir, entry)) else "")
+            results.append(
+                CompletionResult(f"{prefix}{display_dir}{display}", display_text=display)
+            )
+        return self._filter(os.path.basename(filename_part), results)
+
+
+class ChoicesCompleter(BaseCompleter):
+    """Completes option values for any option with fixed ``choices`` (gap fix)."""
+
+    def __init__(self, model: CompletionModel, response_filter: ResponseFilter) -> None:
+        self._index = model
+        self._filter = response_filter
+
+    def complete(self, parsed: ParsedResult) -> list[CompletionResult] | None:
+        if parsed.current_param is None or parsed.current_fragment is None:
+            return None
+        arg = self._index.get_argument_data(
+            parsed.lineage, parsed.current_command, parsed.current_param
+        )
+        if arg is None or not arg.choices:
+            # Fall back to the global table - a global option's value (e.g.
+            # --output) is keyed under ROOT, not the current subcommand.
+            arg = self._index.get_argument_data([], ROOT, parsed.current_param)
+        if arg is None or not arg.choices:
+            return None
+        return self._filter(parsed.current_fragment, [CompletionResult(c) for c in arg.choices])

boto3_s3_cli/autoprompt/model.py

@@ -0,0 +1,198 @@
+"""The completion model: the command/option surface the auto-prompt completes.
+
+aws-cli drives auto-completion from a prebuilt SQLite index of its command
+table. We derive the equivalent from our own ``argparse`` parser
+(:func:`boto3_s3_cli.cli.build_parser`) so there is a single source of truth for
+the option set - the same definitions that dispatch the commands also feed
+completion, and the two cannot drift. :class:`CompletionModel` exposes the small
+query surface the ported :class:`~boto3_s3_cli.autoprompt.parser.CLIParser` and
+completers need (the methods aws-cli's ``ModelIndex`` provides).
+
+Structure note: aws's hierarchy is ``aws s3 <sub>`` (three levels); ours is
+``boto3-s3 <sub>`` (two). The parser normalizes the executable token to
+:data:`ROOT`, so globals live under ``command_name == ROOT`` and the subcommands
+hang directly off ``lineage == [ROOT]``.
+
+Pure Python - no ``prompt_toolkit``, no AWS SDK - so the whole completion
+pipeline is importable and testable without the optional extra.
+"""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import cast
+
+# The executable token the parser normalizes to (aws-cli uses 'aws'). Globals
+# are keyed under this name; the subcommands are its children.
+ROOT = "boto3-s3"
+
+
+@dataclass(frozen=True)
+class ArgData:
+    """Metadata for one option or positional, mirroring aws-cli's ``CLIArgument``.
+
+    ``type_name`` is ``"boolean"`` for flags that take no value (so the parser
+    knows not to consume one) and ``"string"`` otherwise - that is the only
+    distinction the parser acts on. ``choices`` / ``help_text`` are ours, used
+    by the value/name completers; aws keeps the analogous data on its argument
+    model. ``name`` is the hyphenated CLI spelling without the ``--`` (e.g.
+    ``"page-size"``), matching how the parser keys params.
+    """
+
+    name: str
+    type_name: str
+    nargs: object
+    required: bool
+    choices: tuple[str, ...] | None
+    help_text: str | None
+    positional: bool
+
+
+@dataclass(frozen=True)
+class CommandData:
+    """One subcommand's completable surface (its own options + positionals)."""
+
+    help_text: str
+    options: dict[str, ArgData]
+    positionals: tuple[ArgData, ...]
+
+
+class CompletionModel:
+    """The query surface the ported parser and completers consume.
+
+    Methods mirror the names/semantics of aws-cli's ``ModelIndex`` so the port
+    stays faithful: :meth:`command_names`, :meth:`arg_names`,
+    :meth:`get_argument_data`, plus :meth:`global_arg_data` for the option-name
+    completer's global injection.
+    """
+
+    def __init__(self, globals_: dict[str, ArgData], commands: dict[str, CommandData]) -> None:
+        self._globals = globals_
+        self._commands = commands
+
+    def command_names(self, lineage: list[str]) -> list[str]:
+        # Subcommands hang off [ROOT]; nothing nests deeper.
+        if lineage == [ROOT]:
+            return list(self._commands)
+        return []
+
+    def commands_with_full_name(self, lineage: list[str]) -> list[tuple[str, str]]:
+        if lineage == [ROOT]:
+            return [(name, cmd.help_text) for name, cmd in self._commands.items()]
+        return []
+
+    def arg_names(
+        self, lineage: list[str], command_name: str | None, positional_arg: bool = False
+    ) -> list[str]:
+        if command_name == ROOT:
+            return [] if positional_arg else list(self._globals)
+        command = self._commands.get(command_name or "")
+        if command is None:
+            return []
+        if positional_arg:
+            return [arg.name for arg in command.positionals]
+        return list(command.options)
+
+    def get_argument_data(
+        self, lineage: list[str], command_name: str | None, arg_name: str
+    ) -> ArgData | None:
+        if command_name == ROOT:
+            return self._globals.get(arg_name)
+        command = self._commands.get(command_name or "")
+        if command is None:
+            return None
+        if arg_name in command.options:
+            return command.options[arg_name]
+        for positional in command.positionals:
+            if positional.name == arg_name:
+                return positional
+        return None
+
+    def global_arg_data(self) -> list[ArgData]:
+        return list(self._globals.values())
+
+
+def _is_help(action: argparse.Action) -> bool:
+    # Our CLI exposes -h/--help (argparse) but no `help` subcommand; aws-cli is
+    # the reverse (a `help` subcommand, no --help global). Neither tool's help
+    # mechanism is in the other's candidate set, and help is charter-exempt
+    # (overview.md section 3 exception 1), so it is excluded from completion entirely.
+    return "--help" in action.option_strings or "-h" in action.option_strings
+
+
+def _arg_from_action(action: argparse.Action) -> ArgData:
+    # argparse sets nargs=0 for store_true/store_false and our --version action;
+    # those consume no value, so the parser must see them as 'boolean'.
+    type_name = "boolean" if action.nargs == 0 else "string"
+    name = next((opt[2:] for opt in action.option_strings if opt.startswith("--")), action.dest)
+    choices = tuple(str(c) for c in action.choices) if action.choices else None
+    return ArgData(
+        name=name,
+        type_name=type_name,
+        nargs=action.nargs,
+        required=bool(action.required),
+        choices=choices,
+        help_text=action.help,
+        positional=not action.option_strings,
+    )
+
+
+def _actions(parser: argparse.ArgumentParser) -> list[argparse.Action]:
+    return parser._actions  # pyright: ignore[reportPrivateUsage]
+
+
+def subparser_map(parser: argparse.ArgumentParser) -> dict[str, argparse.ArgumentParser]:
+    """The subcommand-name -> subparser map, found via the subparsers action."""
+    for action in _actions(parser):
+        choices = getattr(action, "choices", None)
+        if isinstance(choices, dict):
+            members = cast("dict[object, object]", choices)
+            if all(isinstance(p, argparse.ArgumentParser) for p in members.values()):
+                return cast("dict[str, argparse.ArgumentParser]", choices)
+    raise RuntimeError("boto3-s3 parser has no subparsers")  # pragma: no cover
+
+
+def build_model() -> CompletionModel:
+    """Introspect :func:`boto3_s3_cli.cli.build_parser` into a completion model.
+
+    Globals are the top-level parser's options (added to every subparser via the
+    shared parent, so they are filtered out of each subcommand's own option set
+    by spelling). Imported lazily to keep the module SDK-free and avoid an import
+    cycle - only reached on the auto-prompt path.
+    """
+    from boto3_s3_cli.cli import build_parser
+
+    parser = build_parser()
+
+    # The subparsers action is the top parser's only positional, so the
+    # `not option_strings` guard skips it along with any positional; globals are
+    # exactly the top-level options minus help.
+    global_option_strings: set[str] = set()
+    globals_: dict[str, ArgData] = {}
+    for action in _actions(parser):
+        if _is_help(action) or not action.option_strings:
+            continue
+        global_option_strings.update(action.option_strings)
+        arg = _arg_from_action(action)
+        globals_[arg.name] = arg
+
+    commands: dict[str, CommandData] = {}
+    for name, subparser in subparser_map(parser).items():
+        options: dict[str, ArgData] = {}
+        positionals: list[ArgData] = []
+        for action in _actions(subparser):
+            if _is_help(action):
+                continue
+            if not action.option_strings:
+                positionals.append(_arg_from_action(action))
+            elif not set(action.option_strings) & global_option_strings:
+                arg = _arg_from_action(action)
+                options[arg.name] = arg
+        commands[name] = CommandData(
+            help_text=subparser.description or "",
+            options=options,
+            positionals=tuple(positionals),
+        )
+
+    return CompletionModel(globals_, commands)