`tyro.conf`#

The tyro.conf submodule contains helpers for attaching parsing-specific configuration metadata to types via PEP 593 runtime annotations.

Configuration flags are applied recursively, and should generally be subscripted: Fixed[T], Suppress[T], etc.

Features here are supported, but generally unnecessary and should be used sparingly.

Package Contents#

Returns a metadata object for fine-grained argument configuration with typing.Annotated. Should typically not be required.

x: Annotated[int, tyro.conf.arg(...)]

Parameters:

name – A new name for the argument in the CLI.
metavar – Argument name in usage messages. The type is used by default.
help – Helptext for this argument. The docstring is used by default.
aliases – Aliases for this argument. All strings in the sequence should start with a hyphen (-). Aliases will not currently be prefixed in a nested structure, and are not supported for positional arguments.
prefix_name – Whether or not to prefix the name of the argument based on where it is in a nested structure. Arguments are prefixed by default.
constructor – A constructor type or function. This should either be (a) a subtype of an argument’s annotated type, or (b) a function with type-annotated inputs that returns an instance of the annotated type. This will be used in place of the argument’s type for parsing arguments. No validation is done.
constructor_factory – A function that returns a constructor type or function. Useful when the constructor isn’t immediately available.

Returns:

Object to attach via typing.Annotated[].

tyro.conf.subcommand(name: str | None = None, *, default: Any = MISSING_NONPROP, description: str | None = None, prefix_name: bool = True, constructor: None = None, constructor_factory: Callable[[], Type | Callable] | None = None) → Any[source]#

tyro.conf.subcommand(name: str | None = None, *, default: Any = MISSING_NONPROP, description: str | None = None, prefix_name: bool = True, constructor: Type | Callable | None = None, constructor_factory: None = None) → Any

Returns a metadata object for configuring subcommands with typing.Annotated. Useful for aesthetics.

Consider the standard approach for creating subcommands:

tyro.cli(
    Union[NestedTypeA, NestedTypeB]
)

This will create two subcommands: nested-type-a and nested-type-b.

Annotating each type with tyro.conf.subcommand() allows us to override for each subcommand the (a) name, (b) defaults, (c) helptext, and (d) whether to prefix the name or not.

tyro.cli(
    Union[
        Annotated[
            NestedTypeA, subcommand("a", ...)
        ],
        Annotated[
            NestedTypeB, subcommand("b", ...)
        ],
    ]
)

Parameters:

name – The name of the subcommand in the CLI.
default – A default value for the subcommand, for struct-like types. (eg dataclasses)
description – Description of this option to use in the helptext. Defaults to docstring.
prefix_name – Whether to prefix the name of the subcommand based on where it is in a nested structure.
constructor – A constructor type or function. This should either be (a) a subtype of an argument’s annotated type, or (b) a function with type-annotated inputs that returns an instance of the annotated type. This will be used in place of the argument’s type for parsing arguments. No validation is done.
constructor_factory – A function that returns a constructor type or function. Useful when the constructor isn’t immediately available.

tyro.conf.AvoidSubcommands#

Avoid creating subcommands when a default is provided for unions over nested types. This simplifies CLI interfaces, but makes them less expressive.

Can be used directly on union types, AvoidSubcommands[Union[...]], or recursively applied to nested types.

tyro.conf.ConsolidateSubcommandArgs#

Consolidate arguments applied to subcommands. Makes CLI less sensitive to argument ordering, at the cost of support for optional subcommands.

By default, tyro will generate a traditional CLI interface where args are applied to the directly preceding subcommand. When we have two subcommands s1 and s2:

python x.py {--root options} s1 {--s1 options} s2 {--s2 options}

This can be frustrating because the resulting CLI is sensitive to the positioning of options.

To consolidate subcommands, we push arguments to the end, after all subcommands:

python x.py s1 s2 {--root, s1, and s2 options}

This is more robust to reordering of options, ensuring that any new options can simply be placed at the end of the command.

tyro.conf.Fixed#: A type T can be annotated as Fixed[T] to prevent tyro.cli from parsing it; a default value should be set instead. Fields that can’t be parsed with defaults will also be marked as fixed automatically.

tyro.conf.FlagConversionOff#

Turn off flag conversion for booleans with default values. Instead, types annotated with bool will expect an explicit True or False.

Can be used directly on boolean annotations, FlagConversionOff[bool], or recursively applied to nested types.

tyro.conf.OmitArgPrefixes#

Make flags used for keyword arguments shorter by omitting prefixes.

If we have a structure with the field:

cmd: NestedType

By default, --cmd.arg may be generated as a flag. If prefixes are omitted, we would instead simply have --arg.

tyro.conf.OmitSubcommandPrefixes#

Make CLI inputs used for subcommands shorter by omitting the subcommand-specific portion of the prefix.

If we have a structure with the field:

cmd: Union[NestedTypeA, NestedTypeB]

By default, --cmd.arg may be generated as a flag for each dataclass in the union. If subcommand prefixes are omitted, we would instead have --arg.

By default, cmd:nested-type-a and cmd:nested-type-b may be generated as subcommand. If subcommand prefixes are omitted, we would instead have nested-type-a and nested-type-b.

tyro.conf.Positional#: A type T can be annotated as Positional[T] if we want to parse it as a positional argument.

tyro.conf.PositionalRequiredArgs#: Make all arguments without defaults positional.

tyro.conf.Suppress#: A type T can be annotated as Suppress[T] to prevent tyro.cli from parsing it, and to prevent it from showing up in helptext.

tyro.conf.SuppressFixed#: Hide fields that are either manually or automatically marked as fixed.

tyro.conf.UseAppendAction#

Use “append” actions for variable-length arguments.

Given an annotation like x: list[int], this means that x = [0, 1, 2] can be set via the CLI syntax --x 0 --x 1 --x 2 instead of the default of --x 0 1 2.

The resulting syntax may be more user-friendly; for tyro, it also enables support for otherwise ambiguous annotations like list[list[int]].

Can be applied to all variable-length sequences (list[T], Sequence[T], tuple[T, ...], etc), including dictionaries without default values.

tyro.conf.UseCounterAction#

verbose: UseCounterAction[int].

Type:: Use “counter” actions for integer arguments. Example usage

tyro.conf.configure(*markers: Marker) → Callable[[CallableType], CallableType][source]#

Decorator for applying configuration options.

Configuration markers are implemented via typing.Annotated and straightforward to apply to types, for example:

field: tyro.conf.FlagConversionOff[bool]

This decorator makes markers applicable to general functions as well:

# Recursively apply FlagConversionOff to all fields in `main()`.
@tyro.conf.configure(tyro.conf.FlagConversionOff)
def main(field: bool) -> None:
    ...

Parameters:: markers (Marker) – Options to apply.
Return type:: Callable[[CallableType], CallableType]

tyro.conf#

Package Contents#

`tyro.conf`#