xtr-console 1.0.0__py3-none-any.whl

xtr_console/__init__.py

@@ -0,0 +1,76 @@
+"""Async-native console applications: commands declared once, run on one event loop.
+
+A command is a function, or a class whose instances are callable, declared
+with :func:`as_command`. An :class:`Application` parses the command line,
+supplies a :class:`ConsoleStyle` to any parameter asking for one, and runs
+the command — with its dependencies from a container, when one is wired
+through :mod:`xtr_console.integration.wireup`.
+
+The core has no dependency-injection container of its own, and imports none.
+"""
+
+from importlib.metadata import version
+
+from .application import Application, Hook
+from .command import (
+    CommandArguments,
+    CommandCallable,
+    CommandDescriptor,
+    CommandInvokerInterface,
+    CommandSignature,
+    CommandsLocator,
+    CommandsLocatorInterface,
+    DefaultCommandInvoker,
+    default_registry,
+)
+from .decorator import as_command
+from .exception import (
+    ApplicationAlreadyWiredError,
+    CommandSignatureError,
+    ConsoleError,
+    DuplicateCommandError,
+    EventLoopRunningError,
+    InvalidCommandNameError,
+    InvalidCommandResultError,
+    InvalidDefaultError,
+    MissingContainerError,
+    UnregisteredCommandError,
+)
+from .exit_code import ExitCode
+from .style import ConsoleStyle
+from .tester import ApplicationTester, CommandTester
+from .verbosity import SHELL_VERBOSITY, Verbosity
+
+__version__ = version("xtr-console")
+
+__all__ = [
+    "SHELL_VERBOSITY",
+    "Application",
+    "ApplicationAlreadyWiredError",
+    "ApplicationTester",
+    "CommandArguments",
+    "CommandCallable",
+    "CommandDescriptor",
+    "CommandInvokerInterface",
+    "CommandSignature",
+    "CommandSignatureError",
+    "CommandTester",
+    "CommandsLocator",
+    "CommandsLocatorInterface",
+    "ConsoleError",
+    "ConsoleStyle",
+    "DefaultCommandInvoker",
+    "DuplicateCommandError",
+    "EventLoopRunningError",
+    "ExitCode",
+    "Hook",
+    "InvalidCommandNameError",
+    "InvalidCommandResultError",
+    "InvalidDefaultError",
+    "MissingContainerError",
+    "UnregisteredCommandError",
+    "Verbosity",
+    "__version__",
+    "as_command",
+    "default_registry",
+]

xtr_console/application.py

@@ -0,0 +1,365 @@
+"""A console application: every declared command behind one entry point."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+import sys
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Final, Literal, TypeAlias, cast, final
+
+from cyclopts import App, Group, Parameter
+from cyclopts.exceptions import CycloptsError
+from cyclopts.help import DefaultFormatter, PanelSpec, TableSpec
+from rich import box
+from rich.markup import escape
+from rich.text import Text
+
+from .command import CommandSelection, CommandSignature, DefaultCommandInvoker, default_registry
+from .command.command_descriptor import function_of
+from .exception import EventLoopRunningError, InvalidCommandResultError
+from .exit_code import ExitCode
+from .global_options import GlobalOptions, list_global_options
+from .style import ConsoleStyle
+from .style.console_style import block
+from .style.exception_renderer import render_exception
+from .verbosity import SHELL_VERBOSITY, Verbosity
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Sequence
+
+    from cyclopts.help.protocols import HelpFormatter
+    from rich.padding import Padding
+
+    from .command import (
+        CommandArguments,
+        CommandDescriptor,
+        CommandInvokerInterface,
+        CommandsLocatorInterface,
+    )
+
+__all__ = ["Application", "ConfigureHook", "Hook"]
+
+Hook: TypeAlias = "Callable[[], Awaitable[None] | None]"
+"""Run before or after a command; sync or async."""
+
+ConfigureHook: TypeAlias = "Callable[[ConsoleStyle], Awaitable[None] | None]"
+"""Run with a command's style, its global options applied; sync or async."""
+
+_THEME: Final = {
+    "cyclopts.border": "yellow",
+    "cyclopts.name": "green",
+    "cyclopts.default": "yellow",
+    "cyclopts.choices": "yellow",
+    "cyclopts.env_var": "yellow",
+}
+
+
+@final
+class Application:
+    """Every declared command, parsed and run on one event loop.
+
+    Commands come from the registry ``@as_command`` fills — import the
+    modules declaring them first. The startup hooks, the command and the
+    shutdown hooks run on the same loop, so a resource opened on startup is
+    usable by the command and closed on shutdown.
+
+    Every command takes the global options — ``-v``/``-vv``/``-vvv``, ``-q``,
+    ``--silent``, ``-n``, ``--ansi``/``--no-ansi`` — anywhere on its command
+    line; they set the :class:`ConsoleStyle` it writes through.
+
+    With ``catch_exceptions`` on, an exception escaping a command is reported
+    — its message, or with ``-v`` its traceback — and the run ends with
+    :attr:`ExitCode.FAILURE`; off, it propagates, as a test usually wants.
+    """
+
+    __slots__ = (
+        "_backend",
+        "_catch_exceptions",
+        "_commands",
+        "_configure_hooks",
+        "_description",
+        "_help_formatter",
+        "_invoker",
+        "_name",
+        "_shutdown",
+        "_startup",
+        "_version",
+    )
+
+    def __init__(  # noqa: PLR0913 — settings, all optional, all by keyword but the name.
+        self,
+        name: str = "console",
+        version: str | None = None,
+        *,
+        description: str | None = None,
+        commands: CommandsLocatorInterface | None = None,
+        help_formatter: HelpFormatter | None = None,
+        catch_exceptions: bool = True,
+        backend: Literal["asyncio", "trio"] = "asyncio",
+    ) -> None:
+        """Configure the application; nothing is parsed or built until it runs."""
+        self._name = name
+        self._version = version
+        self._description = description
+        self._commands = commands if commands is not None else default_registry()
+        self._help_formatter = help_formatter if help_formatter is not None else _help_formatter()
+        self._catch_exceptions = catch_exceptions
+        self._backend: Literal["asyncio", "trio"] = backend
+        self._invoker: CommandInvokerInterface = DefaultCommandInvoker()
+        self._configure_hooks: list[ConfigureHook] = []
+        self._startup: list[Hook] = []
+        self._shutdown: list[Hook] = []
+
+    @property
+    def name(self) -> str:
+        """Return the name the application is invoked by."""
+        return self._name
+
+    @property
+    def commands(self) -> CommandsLocatorInterface:
+        """Return the registry the commands are read from."""
+        return self._commands
+
+    def on_configure(self, hook: ConfigureHook) -> None:
+        """Run ``hook`` with the command's style, before the startup hooks.
+
+        The style has the global options applied — the place to make anything
+        else follow ``-v``, ``-q`` or ``--no-ansi``, a logger among them.
+        """
+        self._configure_hooks.append(hook)
+
+    def on_startup(self, hook: Hook) -> None:
+        """Run ``hook`` before the command, on the command's event loop."""
+        self._startup.append(hook)
+
+    def on_shutdown(self, hook: Hook) -> None:
+        """Run ``hook`` after the command, even if it raised."""
+        self._shutdown.append(hook)
+
+    @property
+    def invoker(self) -> CommandInvokerInterface:
+        """Return what builds and calls the commands."""
+        return self._invoker
+
+    def use_invoker(self, invoker: CommandInvokerInterface) -> None:
+        """Have ``invoker`` build and call commands — a container, typically."""
+        self._invoker = invoker
+
+    def run(self, argv: Sequence[str] | None = None) -> int:
+        """Run the command ``argv`` names on a fresh event loop; return its exit code.
+
+        ``argv`` defaults to ``sys.argv[1:]``. Hand the result to the shell::
+
+            raise SystemExit(application.run())
+
+        The verbosity starts from ``SHELL_VERBOSITY``, and what the run settles
+        on is written back to it, for the processes the command starts.
+
+        Raises:
+            EventLoopRunningError: If called from async code; await
+                :meth:`run_async` there.
+        """
+        if _loop_running():
+            raise EventLoopRunningError
+        style = _terminal_style()
+        selection = self._configure(argv, style)
+        os.environ[SHELL_VERBOSITY] = str(style.verbosity.shell_level)
+        app = self._build(style, selection.commands)
+        try:
+            code = cast("int", app(selection.tokens, exit_on_error=False))
+        except CycloptsError:
+            return ExitCode.INVALID
+        except SystemExit as stop:
+            return _exit_code_of(stop, style)
+        return code
+
+    async def run_async(
+        self, argv: Sequence[str] | None = None, *, style: ConsoleStyle | None = None
+    ) -> int:
+        """Run the command ``argv`` names on the running loop; return its exit code.
+
+        Output goes through ``style``, a fresh :class:`ConsoleStyle` on the
+        terminal when omitted — its verbosity read from ``SHELL_VERBOSITY``. A
+        style given keeps its own until a global option changes it. A command
+        that exits — ``sys.exit(3)``, or Ctrl-C, which exits ``130`` — ends the
+        run with that code rather than leaving the process.
+        """
+        style = style if style is not None else _terminal_style()
+        selection = self._configure(argv, style)
+        app = self._build(style, selection.commands)
+        try:
+            code = cast("int", await app.run_async(selection.tokens, exit_on_error=False))
+        except CycloptsError:
+            return ExitCode.INVALID
+        except SystemExit as stop:
+            return _exit_code_of(stop, style)
+        return code
+
+    def _configure(self, argv: Sequence[str] | None, style: ConsoleStyle) -> CommandSelection:
+        """Apply the global options in ``argv`` to ``style``; select from what is left."""
+        options = GlobalOptions.parse(list(argv) if argv is not None else sys.argv[1:])
+        options.apply(style)
+        return CommandSelection.of(self._commands.commands(), options.remaining)
+
+    def _build(self, style: ConsoleStyle, commands: Sequence[CommandDescriptor]) -> App:
+        """Build the parser for ``commands``."""
+        header = self._header()
+        app = App(
+            name=self._name,
+            help=self._description,
+            help_format="rich",
+            help_prologue=header,
+            help_formatter=self._help_formatter,
+            help_flags=("--help", "-h"),
+            version=header if self._version is not None else None,
+            version_format="rich",
+            version_flags=("--version", "-V") if self._version is not None else (),
+            error_formatter=_error_block,
+            default_parameter=Parameter(negative=()),
+            group_commands=Group("Available commands", sort_key=1, theme=_THEME),
+            group_arguments=Group("Arguments", sort_key=1, theme=_THEME),
+            group_parameters=Group("Options", sort_key=2, theme=_THEME),
+            result_action="return_int_as_exit_code_else_zero",
+            backend=self._backend,
+            console=style.console,
+            error_console=style.error_console,
+        )
+        options = Group("Options", sort_key=0, theme=_THEME)
+        for flag in ("--help", "--version") if self._version is not None else ("--help",):
+            app[flag].group = (options,)
+        list_global_options(app, options)
+        namespaces: dict[str, Group] = {}
+        for command in commands:
+            namespace = command.namespace
+            group = (
+                namespaces.setdefault(namespace, Group(namespace, sort_key=3, theme=_THEME))
+                if namespace is not None
+                else app.group_commands
+            )
+            _ = app.command(
+                self._entry_point(command, CommandSignature.of(command), style),
+                name=command.name,
+                alias=command.aliases,
+                group=group,
+                show=not command.hidden,
+                help=command.description,
+            )
+        return app
+
+    def _entry_point(
+        self, command: CommandDescriptor, signature: CommandSignature, style: ConsoleStyle
+    ) -> Callable[..., Awaitable[object]]:
+        """Return what the parser calls: the command line in, the command run.
+
+        It presents the parameters the command line fills, and nothing else;
+        the style and anything a container supplies are added on the way in.
+        What the command returns goes back to the parser, which reads the
+        exit code from it.
+        """
+
+        async def entry(*args: object, **kwargs: object) -> object:
+            bound = signature.command_line.bind(*args, **kwargs)
+            return await self._execute(command, signature.arguments(bound, style), signature, style)
+
+        target = command.target
+        documented = function_of(target) if isinstance(target, type) else target
+        entry.__name__ = command.name
+        entry.__doc__ = inspect.getdoc(documented) or inspect.getdoc(target)
+        entry.__dict__["__signature__"] = signature.command_line
+        return entry
+
+    async def _execute(
+        self,
+        command: CommandDescriptor,
+        arguments: CommandArguments,
+        signature: CommandSignature,
+        style: ConsoleStyle,
+    ) -> object:
+        """Run the configure and startup hooks, the command, then the shutdown hooks.
+
+        Every shutdown hook runs, in the order added, once startup has begun —
+        whether a startup hook, the command or another shutdown hook raised.
+        Whatever raised is one failure, each error chained to the one before.
+        """
+        try:
+            async with AsyncExitStack() as shutdown:
+                for hook in reversed(self._shutdown):
+                    _ = shutdown.push_async_callback(_call, hook)
+                for configure in self._configure_hooks:
+                    configured = configure(style)
+                    if inspect.isawaitable(configured):
+                        await configured
+                for hook in self._startup:
+                    await _call(hook)
+                return _exit_code(
+                    command, await self._invoker.invoke(command, signature, arguments)
+                )
+        except Exception as error:
+            if not self._catch_exceptions:
+                raise
+            render_exception(error, style)
+            return ExitCode.FAILURE
+
+    def _header(self) -> str:
+        name = f"[green]{escape(self._name)}[/green]"
+        return name if self._version is None else f"{name} [yellow]{escape(self._version)}[/yellow]"
+
+
+def _terminal_style() -> ConsoleStyle:
+    """Return a style on the terminal, as verbose as ``SHELL_VERBOSITY`` says."""
+    return ConsoleStyle(verbosity=Verbosity.from_shell(os.environ.get(SHELL_VERBOSITY)))
+
+
+def _help_formatter() -> DefaultFormatter:
+    """Lay help out as open sections, without the boxes."""
+    return DefaultFormatter(
+        panel_spec=PanelSpec(box=box.SIMPLE, padding=(0, 0)),
+        table_spec=TableSpec(show_header=False, box=None, padding=(0, 2)),
+    )
+
+
+def _error_block(error: CycloptsError) -> Padding:
+    return block("ERROR", Text(str(error)), "white on red")
+
+
+async def _call(hook: Hook) -> None:
+    result = hook()
+    if inspect.isawaitable(result):
+        await result
+
+
+def _exit_code(command: CommandDescriptor, result: object) -> int:
+    """Return ``result`` as the exit code it must be.
+
+    Raises:
+        InvalidCommandResultError: If it is not an ``int`` — or is a ``bool``.
+    """
+    if not isinstance(result, int) or isinstance(result, bool):
+        raise InvalidCommandResultError(command.name, type(result).__qualname__)
+    return result
+
+
+def _loop_running() -> bool:
+    try:
+        _ = asyncio.get_running_loop()
+    except RuntimeError:
+        return False
+    return True
+
+
+def _exit_code_of(stop: SystemExit, style: ConsoleStyle) -> int:
+    """Read the exit code the way Python does when a process exits.
+
+    ``None`` is success and an ``int`` is the code; anything else is a
+    message, printed to standard error, and a failure.
+    """
+    match stop.code:
+        case None:
+            return ExitCode.SUCCESS
+        case int():
+            return stop.code
+        case message:
+            style.error_console.print(str(message), markup=False, highlight=False)
+            return ExitCode.FAILURE

xtr_console/command/__init__.py

@@ -0,0 +1,27 @@
+"""Declaring commands, and turning a parsed command line into a call."""
+
+from .command_arguments import CommandArguments
+from .command_callable import CommandCallable
+from .command_descriptor import CommandDescriptor, CommandTarget, default_name_of
+from .command_invoker_interface import CommandInvokerInterface
+from .command_selection import CommandSelection
+from .command_signature import CommandSignature
+from .commands_locator import CommandsLocator
+from .commands_locator_interface import CommandsLocatorInterface
+from .default_command_invoker import DefaultCommandInvoker
+from .default_registry import default_registry
+
+__all__ = [
+    "CommandArguments",
+    "CommandCallable",
+    "CommandDescriptor",
+    "CommandInvokerInterface",
+    "CommandSelection",
+    "CommandSignature",
+    "CommandTarget",
+    "CommandsLocator",
+    "CommandsLocatorInterface",
+    "DefaultCommandInvoker",
+    "default_name_of",
+    "default_registry",
+]

xtr_console/command/command_arguments.py

@@ -0,0 +1,23 @@
+"""What a command is called with."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["CommandArguments"]
+
+
+@dataclass(frozen=True, slots=True)
+class CommandArguments:
+    """The positional and keyword arguments a command is called with.
+
+    Everything the command line and the console supply. Parameters a
+    container fills are not here; the container adds them itself.
+    """
+
+    args: tuple[object, ...] = ()
+    kwargs: Mapping[str, object] = field(default_factory=dict[str, object])

xtr_console/command/command_callable.py

@@ -0,0 +1,23 @@
+"""What a command class's instances must be: callable, returning an exit code."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable
+
+__all__ = ["CommandCallable"]
+
+
+class CommandCallable(Protocol):
+    """An object whose call returns an exit code, now or once awaited.
+
+    ``*args: Any, **kwargs: Any`` is how a type checker spells "any
+    signature": a ``__call__`` taking any parameters matches, and only the
+    return type is held to ``int``.
+    """
+
+    def __call__(self, *args: Any, **kwargs: Any) -> int | Awaitable[int]:
+        """Run the command and return its exit code."""
+        ...

xtr_console/command/command_descriptor.py

@@ -0,0 +1,130 @@
+"""A declared command: what runs, and what it is called."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Final, TypeAlias, cast
+
+from xtr_console.exception import (
+    CommandSignatureError,
+    DuplicateCommandError,
+    InvalidCommandNameError,
+)
+
+__all__ = ["CommandDescriptor", "CommandTarget", "call_of", "default_name_of", "function_of"]
+
+CommandTarget: TypeAlias = Callable[..., object] | type
+"""A command function, or a class whose instances are the command."""
+
+_NAMESPACE_SEPARATOR: Final = ":"
+_WORD_BOUNDARY: Final = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
+_CLASS_SUFFIX: Final = "Command"
+
+
+@dataclass(frozen=True, slots=True)
+class CommandDescriptor:
+    """A declared command.
+
+    ``target`` is what was declared: a function, or a class whose instances
+    are callable — built only when its command runs. ``name`` is what the
+    command is invoked by; a ``namespace:`` prefix groups it with its
+    siblings in the command list. ``description`` replaces the summary the
+    docstring would otherwise supply.
+
+    Raises:
+        InvalidCommandNameError: If the name or an alias is empty, holds
+            whitespace, or starts with ``-``.
+        DuplicateCommandError: If the command repeats one of its own names.
+        CommandSignatureError: If ``target`` is a class that defines no
+            ``__call__``, or is a generator — calling one runs nothing.
+    """
+
+    target: CommandTarget
+    name: str
+    aliases: tuple[str, ...] = ()
+    description: str | None = None
+    hidden: bool = False
+
+    def __post_init__(self) -> None:
+        """Refuse what the command line could not call, or could not type."""
+        for name in self.names:
+            _check_name(name)
+        for position, name in enumerate(self.names):
+            if name in self.names[:position]:
+                raise DuplicateCommandError(name, self.name)
+        called = function_of(self.target)
+        if called is None:
+            raise CommandSignatureError(self.name, "a command class must define __call__")
+        if inspect.isgeneratorfunction(called) or inspect.isasyncgenfunction(called):
+            raise CommandSignatureError(self.name, "a command cannot be a generator")
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        """Return the name, then every alias."""
+        return (self.name, *self.aliases)
+
+    @property
+    def namespace(self) -> str | None:
+        """Return what precedes the first ``:`` in the name, if anything does."""
+        namespace, separator, _ = self.name.partition(_NAMESPACE_SEPARATOR)
+        return namespace if separator else None
+
+
+def default_name_of(target: CommandTarget) -> str:
+    """Name a command after what declares it.
+
+    A function ``create_user`` becomes ``create-user``; a class
+    ``ImportUsersCommand`` becomes ``import-users``.
+    """
+    name = cast("str", getattr(target, "__name__", type(target).__name__))
+    if isinstance(target, type):
+        name = name.removesuffix(_CLASS_SUFFIX) or name
+        name = _WORD_BOUNDARY.sub("_", name)
+    return name.strip("_").lower().replace("_", "-")
+
+
+def call_of(command_type: type) -> Callable[..., object] | None:
+    """Return the ``__call__`` ``command_type`` defines, if any.
+
+    Not ``getattr``: every class inherits ``type.__call__`` from its
+    metaclass — the thing that makes ``Thing()`` build one — so asking a class
+    for its ``__call__`` always finds something.
+    """
+    for ancestor in command_type.__mro__[:-1]:
+        found: Callable[..., object] | None = ancestor.__dict__.get("__call__")
+        if found is not None:
+            return found
+    return None
+
+
+def function_of(target: CommandTarget) -> Callable[..., object] | None:
+    """Return the function that runs when ``target``'s command runs.
+
+    For a class, its ``__call__`` — unwrapped when it is a ``staticmethod``
+    or a ``classmethod``; for a callable object, its type's ``__call__``.
+    """
+    if not isinstance(target, type):
+        return target if inspect.isroutine(target) else call_of(type(target))
+    called = call_of(target)
+    if isinstance(called, (staticmethod, classmethod)):
+        unwrapped: Callable[..., object] = called.__func__
+        return unwrapped
+    return called
+
+
+def _check_name(name: str) -> None:
+    """Refuse a name nobody could type as a command.
+
+    Raises:
+        InvalidCommandNameError: If it is empty, holds whitespace, or
+            starts with ``-`` — the command line would read it as an option.
+    """
+    if not name:
+        raise InvalidCommandNameError(name, "it is empty")
+    if any(character.isspace() for character in name):
+        raise InvalidCommandNameError(name, "it holds whitespace")
+    if name.startswith("-"):
+        raise InvalidCommandNameError(name, "it starts with '-', like an option")

xtr_console/command/command_invoker_interface.py

@@ -0,0 +1,31 @@
+"""The contract for running a command once the command line is parsed."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .command_arguments import CommandArguments
+    from .command_descriptor import CommandDescriptor
+    from .command_signature import CommandSignature
+
+__all__ = ["CommandInvokerInterface"]
+
+
+@runtime_checkable
+class CommandInvokerInterface(Protocol):
+    """Builds what a command needs and calls it.
+
+    The seam a dependency-injection container plugs into: the application
+    parses the command line, and the invoker decides how the command and its
+    remaining parameters come to be.
+    """
+
+    async def invoke(
+        self,
+        command: CommandDescriptor,
+        signature: CommandSignature,
+        arguments: CommandArguments,
+    ) -> object:
+        """Run ``command`` with ``arguments`` and return what it returned."""
+        ...