xtr_console.command ¶
Declaring commands, and turning a parsed command line into a call.
COMMANDS_ATTRIBUTE
module-attribute
¶
Where :func:~xtr_console.as_command records per-target descriptors.
CommandTarget ¶
A command function, or a class whose instances are the command.
CommandArguments
dataclass
¶
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:
-
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
targetis a class that defines no__call__, or is a generator — calling one runs nothing.
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
¶
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, oracme 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
¶
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:
ConsoleStylereceives the style the application writes through. - a container: a parameter annotated for injection —
Injected[T],Autowire(...)orTarget(...)— 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
¶
Every parameter, annotations evaluated; self dropped for a class.
call
instance-attribute
¶
What the command is called with, before a container adds its share.
of
classmethod
¶
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--helpover, a parameter a container fills cannot be passed by keyword, anArgument/Optionmarker does not match the parameter's place, or a parameter carries the parser's own settings.
arguments ¶
Build the call from what the command line bound, adding the style.
CommandsLocator ¶
Bases: CommandsLocatorInterface
Holds every declared command, keyed by each name it answers to.
Start empty.
register ¶
Add command and return it.
Raises:
-
DuplicateCommandError–If its name or an alias is already taken.
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.
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 ¶
Name a command after what declares it.
A function create_user becomes create-user; a class
ImportUsersCommand becomes import-users.