:py:mod:`tyro.extras` ===================== .. py:module:: tyro.extras .. autoapi-nested-parse:: The :mod:`tyro.extras` submodule contains helpers that complement :func:`tyro.cli()`. .. warning:: Compared to the core interface, APIs here are more likely to be changed or deprecated. Package Contents ---------------- .. py:function:: set_accent_color(accent_color: Optional[str]) -> None Set an accent color to use in help messages. Takes any color supported by ``rich``, see ``python -m rich.color``. Experimental. .. py:function:: get_parser(f: tyro._typing.TypeForm[OutT], *, prog: None | str = None, description: None | str = None, default: None | OutT = None, use_underscores: bool = False, console_outputs: bool = True, config: None | Sequence[tyro.conf._markers.Marker] = None, registry: None | tyro.constructors.ConstructorRegistry = None) -> tyro._argparse.ArgumentParser get_parser(f: Callable[Ellipsis, OutT], *, prog: None | str = None, description: None | str = None, default: None | OutT = None, use_underscores: bool = False, console_outputs: bool = True, config: None | Sequence[tyro.conf._markers.Marker] = None, registry: None | tyro.constructors.ConstructorRegistry = None) -> tyro._argparse.ArgumentParser Get the :py:class:`argparse.ArgumentParser` object generated under-the-hood by :func:`tyro.cli`. Useful for tools like ``sphinx-argparse``, ``argcomplete``, etc. For tab completion, we recommend using :func:`tyro.cli`'s built-in ``--tyro-write-completion`` flag. :param f: The function or type to populate from command-line arguments. :param prog: The name of the program to display in the help text. :param description: The description text shown at the top of the help output. :param default: An instance to use for default values. :param use_underscores: If True, uses underscores as word delimiters in the help text. :param console_outputs: If set to False, suppresses parsing errors and help messages. :param config: A sequence of configuration marker objects from :mod:`tyro.conf`. :param registry: A :class:`tyro.constructors.ConstructorRegistry` instance containing custom constructor rules. .. py:function:: overridable_config_cli(configs: Mapping[str, Tuple[str, T]], *, prog: str | None = None, description: str | None = None, args: Sequence[str] | None = None, use_underscores: bool = False, console_outputs: bool = True, config: Sequence[Any] | None = None, sort_subcommands: bool = False, registry: tyro.constructors.ConstructorRegistry | None = None) -> T Helper function for creating a CLI interface that allows us to choose between default config objects (typically dataclasses) and override values within it. Turns off subcommand creation for any union types within the config object. This is a lightweight wrapper over :func:`tyro.cli()`, with some default arguments populated. Also see :func:`tyro.extras.subcommand_type_from_defaults()`. Example usage: .. code-block:: python import dataclasses import tyro @dataclasses.dataclass class Config: a: int b: str default_configs = { "small": ( "Small config", Config(1, "small"), ), "big": ( "Big config", Config(100, "big"), ), } config = tyro.extras.overridable_config_cli(default_configs) print(config) :param configs: A dictionary of config names mapped to a tuple of (description, config object). :param prog: The name of the program printed in helptext. Mirrors argument from `argparse.ArgumentParser()`. :param description: Description text for the parser, displayed when the --help flag is passed in. If not specified, the class docstring is used. Mirrors argument from `argparse.ArgumentParser()`. :param args: If set, parse arguments from a sequence of strings instead of the commandline. Mirrors argument from `argparse.ArgumentParser.parse_args()`. :param use_underscores: If True, use underscores as a word delimiter instead of hyphens. This primarily impacts helptext; underscores and hyphens are treated equivalently when parsing happens. We default helptext to hyphens to follow the GNU style guide. https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html :param console_outputs: If set to `False`, parsing errors and help messages will be suppressed. :param config: Sequence of config marker objects, from `tyro.conf`. We include :class:`tyro.conf.AvoidSubcommands` by default. :param sort_subcommands: If True, sort the subcommands alphabetically by name. :param registry: A :class:`tyro.constructors.ConstructorRegistry` instance containing custom constructor rules. .. py:function:: subcommand_type_from_defaults(defaults: Mapping[str, T], descriptions: Mapping[str, str] = {}, *, prefix_names: bool = True, sort_subcommands: bool = False) -> tyro._typing.TypeForm[T] Construct a Union type for defining subcommands that choose between defaults. For example, when ``defaults`` is set to: .. code-block:: python { "small": Config(...), "big": Config(...), } We return: .. code-block:: python Union[ Annotated[ Config, tyro.conf.subcommand("small", default=Config(...)) ], Annotated[ Config, tyro.conf.subcommand("big", default=Config(...)) ] ] Direct use of :py:data:`typing.Union` and :func:`tyro.conf.subcommand()` should generally be preferred, but this function can be helpful for succinctness. .. warning:: The type returned by this function can be safely used as an input to :func:`tyro.cli()`, but for static analysis when used for annotations we recommend applying a `TYPE_CHECKING` guard: .. code-block:: python from typing import TYPE_CHECKING if TYPE_CHECKING: # Static type seen by language servers, type checkers, etc. SelectableConfig = Config else: # Runtime type used by tyro. SelectableConfig = subcommand_type_from_defaults(...) :param defaults: A dictionary of default subcommand instances. :param descriptions: A dictionary conttaining descriptions for helptext. :param prefix_names: Whether to prefix subcommand names. :param sort_subcommands: If True, sort the subcommands alphabetically by name. :returns: A subcommand type, which can be passed to :func:`tyro.cli`. .. py:function:: literal_type_from_choices(choices: Iterable[T]) -> tyro._typing.TypeForm[T] Generate a :py:data:`typing.Literal` type that constrains values to a set of choices. Using ``Literal[...]`` directly should generally be preferred, but this function can be helpful when choices are generated dynamically. .. warning:: The type returned by this function can be safely used as an input to :func:`tyro.cli()`, but for static analysis when used for annotations we recommend applying a `TYPE_CHECKING` guard: .. code-block:: python from typing import TYPE_CHECKING if TYPE_CHECKING: # Static type seen by language servers, type checkers, etc. Color = str else: # Runtime type used by tyro. Color = literal_type_from_choices(["red", "green", "blue"]) :param choices: Options to choose from. :returns: A type that can be passed to :func:`tyro.cli()`. .. py:function:: from_yaml(cls: Type[DataclassType], stream: Union[str, IO[str], bytes, IO[bytes]]) -> DataclassType Re-construct a dataclass instance from a yaml-compatible string, which should be generated from :func:`tyro.extras.to_yaml()`. .. warning:: **Deprecated.** Serialization functionality is stable but deprecated. It may be removed in a future version of :code:`tyro`. As a secondary feature aimed at enabling the use of :func:`tyro.cli` for general configuration use cases, we also introduce functions for human-readable dataclass serialization: :func:`tyro.extras.from_yaml` and :func:`tyro.extras.to_yaml` attempt to strike a balance between flexibility and robustness — in contrast to naively dumping or loading dataclass instances (via pickle, PyYAML, etc), explicit type references enable custom tags that are robust against code reorganization and refactor, while a PyYAML backend enables serialization of arbitrary Python objects. :param cls: Type to reconstruct. :param stream: YAML to read from. :returns: Instantiated dataclass. .. py:function:: to_yaml(instance: Any) -> str Serialize a dataclass; returns a yaml-compatible string that can be deserialized via :func:`tyro.extras.from_yaml()`. .. warning:: **Deprecated.** Serialization functionality is stable but deprecated. It may be removed in a future version of :code:`tyro`. As a secondary feature aimed at enabling the use of :func:`tyro.cli` for general configuration use cases, we also introduce functions for human-readable dataclass serialization: :func:`tyro.extras.from_yaml` and :func:`tyro.extras.to_yaml` attempt to strike a balance between flexibility and robustness — in contrast to naively dumping or loading dataclass instances (via pickle, PyYAML, etc), explicit type references enable custom tags that are robust against code reorganization and refactor, while a PyYAML backend enables serialization of arbitrary Python objects. :param instance: Dataclass instance to serialize. :returns: YAML string. .. py:class:: SubcommandApp This class provides a decorator-based API for subcommands in :mod:`tyro`, inspired by click. Under-the-hood, this is a light wrapper over :func:`tyro.cli`. Example: .. code-block:: python from tyro.extras import SubcommandApp app = SubcommandApp() @app.command def greet(name: str, loud: bool = False): '''Greet someone.''' greeting = f"Hello, {name}!" if loud: greeting = greeting.upper() print(greeting) @app.command(name="addition") def add(a: int, b: int): '''Add two numbers.''' print(f"{a} + {b} = {a + b}") if __name__ == "__main__": app.cli() Usage: .. code-block:: bash python my_script.py greet Alice python my_script.py greet Bob --loud python my_script.py addition 5 3 .. py:method:: command(func: CallableT) -> CallableT command(func: None = None, *, name: str | None = None) -> Callable[[CallableT], CallableT] A decorator to register a function as a subcommand. This method is inspired by Click's ``@cli.command()`` decorator. It adds the decorated function to the list of subcommands. :param func: The function to register as a subcommand. If None, returns a function to use as a decorator. :param name: The name of the subcommand. If None, the name of the function is used. .. py:method:: cli(*, prog: str | None = None, description: str | None = None, args: Sequence[str] | None = None, use_underscores: bool = False, console_outputs: bool = True, config: Sequence[Any] | None = None, sort_subcommands: bool = False, registry: tyro.constructors.ConstructorRegistry | None = None) -> Any Run the command-line interface. This method creates a CLI using tyro, with all subcommands registered using :func:`command()`. :param prog: The name of the program printed in helptext. Mirrors argument from `argparse.ArgumentParser()`. :param description: Description text for the parser, displayed when the --help flag is passed in. If not specified, the class docstring is used. Mirrors argument from `argparse.ArgumentParser()`. :param args: If set, parse arguments from a sequence of strings instead of the commandline. Mirrors argument from `argparse.ArgumentParser.parse_args()`. :param use_underscores: If True, use underscores as a word delimiter instead of hyphens. This primarily impacts helptext; underscores and hyphens are treated equivalently when parsing happens. We default helptext to hyphens to follow the GNU style guide. https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html :param console_outputs: If set to `False`, parsing errors and help messages will be suppressed. :param config: Sequence of config marker objects, from `tyro.conf`. :param sort_subcommands: If True, sort the subcommands alphabetically by name. :param registry: A :class:`tyro.constructors.ConstructorRegistry` instance containing custom constructor rules. .. py:function:: subcommand_cli_from_dict(subcommands: Dict[str, Callable[Ellipsis, T]], *, prog: str | None = None, description: str | None = None, args: Sequence[str] | None = None, use_underscores: bool = False, console_outputs: bool = True, config: Sequence[tyro.conf._markers.Marker] | None = None, sort_subcommands: bool = False, registry: tyro.constructors.ConstructorRegistry | None = None) -> T subcommand_cli_from_dict(subcommands: Dict[str, Callable[Ellipsis, Any]], *, prog: str | None = None, description: str | None = None, args: Sequence[str] | None = None, use_underscores: bool = False, console_outputs: bool = True, config: Sequence[tyro.conf._markers.Marker] | None = None, sort_subcommands: bool = False, registry: tyro.constructors.ConstructorRegistry | None = None) -> Any Generate a subcommand CLI from a dictionary of functions. For an input like: .. code-block:: python tyro.extras.subcommand_cli_from_dict( { "checkout": checkout, "commit": commit, } ) This is internally accomplished by generating and calling: .. code-block:: python from typing import Annotated, Any, Union import tyro tyro.cli( Union[ Annotated[ Any, tyro.conf.subcommand(name="checkout", constructor=checkout), ], Annotated[ Any, tyro.conf.subcommand(name="commit", constructor=commit), ], ] ) :param subcommands: Dictionary that maps the subcommand name to function to call. :param prog: The name of the program printed in helptext. Mirrors argument from :py:class:`argparse.ArgumentParser`. :param description: Description text for the parser, displayed when the --help flag is passed in. If not specified, `f`'s docstring is used. Mirrors argument from :py:class:`argparse.ArgumentParser`. :param args: If set, parse arguments from a sequence of strings instead of the commandline. Mirrors argument from :py:meth:`argparse.ArgumentParser.parse_args()`. :param use_underscores: If True, use underscores as a word delimeter instead of hyphens. This primarily impacts helptext; underscores and hyphens are treated equivalently when parsing happens. We default helptext to hyphens to follow the GNU style guide. https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html :param console_outputs: If set to ``False``, parsing errors and help messages will be supressed. This can be useful for distributed settings, where :func:`tyro.cli()` is called from multiple workers but we only want console outputs from the main one. :param config: Sequence of config marker objects, from :mod:`tyro.conf`. :param registry: A :class:`tyro.constructors.ConstructorRegistry` instance containing custom constructor rules.