Skip to content

xtr_console.decorator

The declarations an application writes on its own functions, classes and parameters.

as_command declares a command; Argument and Option say what one of its parameters looks like on the command line, attached with Annotated::

async def export(
    io: ConsoleStyle,
    path: Annotated[Path, Argument(help="Where to write.")],
    *,
    force: Annotated[bool, Option(alias="-f")] = False,
) -> int: ...

Whether a parameter is an argument or an option is still its place in the signature — before a bare * or after it. The marker only fine-tunes it, and must match that place.

Argument dataclass

Argument(name: str | None = None, help: str | None = None, env_var: str | None = None, validator: Validator | None = None)

Settings for a parameter taken by position — one before a bare *.

Attributes:

  • name (str | None) –

    The name shown in the usage line and the help, instead of the parameter's.

  • help (str | None) –

    The description, instead of the docstring's Args: entry.

  • env_var (str | None) –

    A variable read when the argument is left out; the command line wins.

  • validator (Validator | None) –

    Called with the converted value; raising ValueError refuses it, and the run ends INVALID with the error's message.

Option dataclass

Option(name: str | None = None, alias: str | tuple[str, ...] = (), help: str | None = None, env_var: str | None = None, negative: str | None = None, count: bool = False, validator: Validator | None = None)

Settings for a parameter taken as --name — one after a bare *.

Attributes:

  • name (str | None) –

    The option's name on the command line ("--from" or "from"), when the parameter's own cannot be it.

  • alias (str | tuple[str, ...]) –

    Other names it answers to, such as "-f".

  • help (str | None) –

    The description, instead of the docstring's Args: entry.

  • env_var (str | None) –

    A variable read when the option is left out; the command line wins.

  • negative (str | None) –

    The name that switches a flag off, such as "--no-cache". A flag has none unless one is given.

  • count (bool) –

    On an int: each repetition adds one — -ddd is 3.

  • validator (Validator | None) –

    Called with the converted value; raising ValueError refuses it, and the run ends INVALID with the error's message.

aliases property

aliases: tuple[str, ...]

:attr:alias as a tuple, however it was given.