Skip to content

xtr_console.command

Declaring commands, and turning a parsed command line into a call.

COMMANDS_ATTRIBUTE module-attribute

COMMANDS_ATTRIBUTE = '__xtr_console_commands__'

Where :func:~xtr_console.as_command records per-target descriptors.

CommandTarget

CommandTarget = Callable[..., object] | type

A command function, or a class whose instances are the command.

CommandArguments dataclass

CommandArguments(args: tuple[object, ...] = (), kwargs: Mapping[str, object] = dict[str, object]())

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.

CommandCallable

Bases: 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.

CommandDescriptor dataclass

CommandDescriptor(target: CommandTarget, name: str, aliases: tuple[str, ...] = (), description: str | None = None, hidden: bool = False)

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:

names property

names: tuple[str, ...]

Return the name, then every alias.

namespace property

namespace: str | None

Return what precedes the first : in the name, if anything does.

CommandInvokerInterface

Bases: 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.

invoke async

invoke(command: CommandDescriptor, signature: CommandSignature, arguments: CommandArguments) -> object

Run command with arguments and return what it returned.

CommandSelection dataclass

CommandSelection(commands: tuple[CommandDescriptor, ...], tokens: tuple[str, ...])

The commands to hand the parser, and the tokens to parse.

  • A command line naming a command needs only that command: the parser's cost grows with every command it holds, faster than linearly.
  • A command line naming a namespace — acme user, or acme user --help — lists the commands in it: they are selected, and the tokens become a request for help.
  • Anything else — no command, --help, a name nothing answers to — needs them all, for the list or to suggest the nearest name.

of classmethod

of(declared: Sequence[CommandDescriptor], tokens: Sequence[str]) -> CommandSelection

Select from declared what tokens needs.

CommandSignature dataclass

CommandSignature(callable_signature: Signature, command_line: Signature, call: Signature, styled: tuple[str, ...], injected: tuple[str, ...])

A command's parameters, sorted by who supplies them.

Three parties fill a command's parameters:

  • the command line: everything not claimed by the other two. A parameter before a bare * is an argument, taken by position; one after it is an option, taken as --name.
  • the console: a parameter annotated :class:ConsoleStyle receives the style the application writes through.
  • a container: a parameter annotated for injection — Injected[T], Autowire(...) or Target(...) — is left for the container, when one is wired.

Annotations are evaluated here, against the module declaring the command, so from __future__ import annotations needs no special care.

callable_signature instance-attribute

callable_signature: Signature

Every parameter, annotations evaluated; self dropped for a class.

command_line instance-attribute

command_line: Signature

What the command line parses.

call instance-attribute

call: Signature

What the command is called with, before a container adds its share.

of classmethod

of(command: CommandDescriptor) -> CommandSignature

Sort the parameters of command.

Raises:

  • CommandSignatureError –

    If an annotation cannot be evaluated, the command is not annotated to return an int, a parameter would take --help over, a parameter a container fills cannot be passed by keyword, an Argument / Option marker does not match the parameter's place, or a parameter carries the parser's own settings.

arguments

arguments(bound: BoundArguments, style: ConsoleStyle) -> CommandArguments

Build the call from what the command line bound, adding the style.

CommandsLocator

CommandsLocator()

Bases: CommandsLocatorInterface

Holds every declared command, keyed by each name it answers to.

Start empty.

register

register(command: CommandDescriptor) -> CommandDescriptor

Add command and return it.

Raises:

commands

commands() -> tuple[CommandDescriptor, ...]

Return every command, in the order declared.

CommandsLocatorInterface

Bases: Protocol

Holds every declared command.

Declaring a command writes to it and building an application reads from it; they are the same registry, so the contract covers both.

register

register(command: CommandDescriptor) -> CommandDescriptor

Add command and return it.

commands

commands() -> tuple[CommandDescriptor, ...]

Return every command, in the order declared.

DefaultCommandInvoker

Bases: CommandInvokerInterface

Calls a function command directly, and builds a command class bare.

A class is built only when its command runs, so declaring many costs nothing. Sync and async commands both work; a sync one runs on the event loop, so it should not block for long.

invoke async

invoke(command: CommandDescriptor, signature: CommandSignature, arguments: CommandArguments) -> object

Run command and return what it returned.

Raises:

  • MissingContainerError –

    If the command, or its class's constructor, needs parameters only a container can supply.

default_name_of

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.