tyro._backends._completion._spec

Completion specification format and serialization.

This module defines the JSON-serializable completion spec format used by the embedded Python completion logic in bash/zsh scripts.

Module Contents

class tyro._backends._completion._spec.OptionSpec[source]

Bases: TypedDict

Specification for a single CLI option.

flags: List[str]

Option flags (e.g., [“-h”, “–help”] or [”–config”]).

description: str

Human-readable description shown in completions.

type: str

“flag”, “value”, “choice”, “boolean”, or “path”.

Type:

Option type

cascade: NotRequired[bool]

Whether this option cascades to subcommands.

nargs: NotRequired[int | str | None]

Number of arguments (e.g., None, “?”, “*”, “+”, or an int).

choices: NotRequired[List[str]]

Valid choices when type is “choice”.

class tyro._backends._completion._spec.SubcommandSpec[source]

Bases: TypedDict

Specification for a subcommand and its nested structure.

description: str

Human-readable description of the subcommand.

options: List[OptionSpec]

Options available for this subcommand.

subcommands: Dict[str, SubcommandSpec]

Nested subcommands, keyed by name.

frontier_groups: List[List[str]]

Groups of mutually exclusive subcommand choices.

When multiple independent subcommand selections exist at this level (e.g., choosing both a model AND an optimizer), each inner list represents one group of mutually exclusive choices. The completion system uses this to track which groups have been satisfied and which still need selection.

Empty when there’s only one subcommand group (standard subcommands).

class tyro._backends._completion._spec.CompletionSpec[source]

Bases: TypedDict

Root completion specification for a CLI program.

prog: str

Program name.

options: List[OptionSpec]

Top-level options.

subcommands: Dict[str, SubcommandSpec]

Top-level subcommands, keyed by name.

frontier_groups: List[List[str]]

Groups of mutually exclusive subcommand choices at the root level.

See SubcommandSpec.frontier_groups for detailed explanation.

tyro._backends._completion._spec.build_completion_spec(parser_spec: tyro._parsers.ParserSpecification, prog: str) → CompletionSpec[source]

Build a completion specification from a ParserSpecification.

Parameters:
Returns:

Completion spec for the CLI program.

Return type:

CompletionSpec