tyro.constructors

The tyro.constructors submodule exposes tyro’s API for defining behavior for different types.

Warning

This submodule is not needed for the majority of users.

Package Contents

tyro.constructors.MISSING: Any

Sentinel value to mark default values as missing. Can be used to mark fields passed in via default= for tyro.cli() as required.

When used, the ‘missing’ semantics propagate to children. For example, if we write:

def main(inner: Dataclass = tyro.MISSING) -> None:
    ...

tyro.cli(main)

then all fields belonging to Dataclass will be marked as missing, even if a default exists in the dataclass definition.

tyro.constructors.MISSING_NONPROP: Any

Non-propagating version of tyro.MISSING.

When used, the ‘missing’ semantics do not propagate to children. For example:

def main(inner: Dataclass = tyro.MISSING_NONPROP) -> None:
    ...

tyro.cli(main)

is equivalent to:

def main(inner: Dataclass) -> None:
    ...

tyro.cli(main)

where default values for fields belonging to Dataclass will be taken from the dataclass definition.

class tyro.constructors.PrimitiveConstructorSpec

Bases: Generic[T]

Specification for constructing a primitive type from a string.

There are two ways to use this class:

First, we can include it in a type signature via typing.Annotated. This is the simplest for making local modifications to parsing behavior for individual fields.

Alternatively, it can be returned by a rule in a ConstructorRegistry.

nargs: int | tuple[int, Ellipsis] | Literal[*]

Number of arguments required to construct an instance. If nargs is “*”, then the number of arguments is variable. If nargs is a tuple, it represents multiple valid fixed argument counts (used for unions with different fixed nargs).

metavar: str

Metavar to display in help messages.

instance_from_str: Callable[[list[str]], T]

Given a list of string arguments, construct an instance of the type. The length of the list will match the value of nargs.

is_instance: Callable[[Any], bool | Literal[~]]

Given an object instance, does it match this primitive type? This is used for specific help messages when both a union type is present and a default is provided.

Can return “~” to signify that an instance is a “fuzzy” match, and should only be used if there are no other matches. This is used for numeric tower support.

str_from_instance: Callable[[T], list[str]]

Convert an instance to a list of string arguments that would construct the instance. This is used for help messages when a default is provided.

choices: tuple[str, Ellipsis] | None

Finite set of choices for arguments.

class tyro.constructors.PrimitiveTypeInfo

Information used to generate constructors for primitive types.

type: Type

Annotated field type. Forward references, aliases, and type variables/parameters will have been resolved and runtime annotations (typing.Annotated) will have been stripped.

type_origin: Type | None

The output of get_origin() on the static type.

markers: set[tyro.conf._markers.Marker]

Set of tyro markers used to configure this field.

static make(raw_annotation: Type | Callable, parent_markers: set[tyro.conf._markers.Marker], exclude_markers: set[tyro.conf._markers.Marker] | None = None) → PrimitiveTypeInfo

Parameters:

• raw_annotation (Type | Callable)

• parent_markers (set[tyro.conf._markers.Marker])

• exclude_markers (set[tyro.conf._markers.Marker] | None)

Return type:

PrimitiveTypeInfo

exception tyro.constructors.UnsupportedTypeAnnotationError(message: tuple[tyro._fmtlib._Text, Ellipsis])

Bases: Exception

Exception raised when a type annotation is not supported.

Parameters:

message (tuple[tyro._fmtlib._Text, Ellipsis])

class tyro.constructors.ConstructorRegistry

Registry for rules that define how types are constructed from command-line arguments.

The behavior of CLIs generated by tyro are based on two types of rules.

Primitive rules should be a callable with the signature:

where None is returned if the rule doesn’t apply, and UnsupportedTypeAnnotationError is returned if the rule applies but an error was encountered. Each primitive rule defines behavior for a type that can be instantiated from a single command-line argument.

Struct rules should be a callable with the signature:

where None is returned if the rule doesn’t apply. Each struct rule defines behavior for a type that can be instantiated from multiple command-line arguments.

To activate a registry, pass it directly to tyro.cli():

For backward compatibility, you can also use the context manager pattern, though the direct parameter approach is recommended:

primitive_rule(rule: PrimitiveSpecRule) → PrimitiveSpecRule

Define a rule for constructing a primitive type from a string. The most recently added rule will be applied first.

Custom primitive rules will take precedence over both default primitive rules and struct rules

Parameters:

rule (PrimitiveSpecRule)

Return type:

PrimitiveSpecRule

struct_rule(rule: StructSpecRule) → StructSpecRule

Define a rule for constructing a primitive type from a string. The most recently added rule will be applied first.

Parameters:

rule (StructSpecRule)

Return type:

StructSpecRule

classmethod get_primitive_spec(type_info: tyro.constructors._primitive_spec.PrimitiveTypeInfo, nondefault_only: bool = False) → tyro.constructors._primitive_spec.PrimitiveConstructorSpec | tyro.constructors._primitive_spec.UnsupportedTypeAnnotationError

Get a constructor specification for a given type.

Parameters:

• type_info (tyro.constructors._primitive_spec.PrimitiveTypeInfo)

• nondefault_only (bool)

Return type:

tyro.constructors._primitive_spec.PrimitiveConstructorSpec | tyro.constructors._primitive_spec.UnsupportedTypeAnnotationError

classmethod get_struct_spec(type_info: tyro.constructors._struct_spec.StructTypeInfo) → tyro.constructors._struct_spec.StructConstructorSpec | tyro.constructors._struct_spec.InvalidDefaultInstanceError | None

Get a constructor specification for a given type.

Returns:

• StructConstructorSpec if the type can be handled as a struct.

• InvalidDefaultInstanceError if the type can be handled, but the provided default instance is incompatible with the type.

• None if the type cannot be handled as a struct (no matching rule found).

Parameters:

type_info (tyro.constructors._struct_spec.StructTypeInfo)

Return type:

tyro.constructors._struct_spec.StructConstructorSpec | tyro.constructors._struct_spec.InvalidDefaultInstanceError | None

__enter__() → None

Return type:

None

__exit__(*args: Any) → None

Parameters:

args (Any)

Return type:

None

class tyro.constructors.StructConstructorSpec

Specification for a struct type, which is broken down into multiple fields.

Each struct type is instantiated by calling an instantiate(**kwargs) function with keyword a set of keyword arguments.

Unlike PrimitiveConstructorSpec, there is only one way to use this class. It must be returned by a rule in ConstructorRegistry.

instantiate: Callable[Ellipsis, Any]

Function to call to instantiate the struct.

fields: tuple[StructFieldSpec, Ellipsis]

Fields used to construct the callable. Each field is used as a keyword argument for the instantiate(**kwargs) function.

class tyro.constructors.StructFieldSpec

Behavior specification for a single field in our callable.

name: str

The name of the field. This will be used as a keyword argument for the struct’s associated instantiate(**kwargs) function.

type: Type

The type of the field. Can be either a primitive or a nested struct type.

default: Any

The default value of the field.

helptext: str | Callable[[], str | None] | None

Helptext for the field.

is_default_overridden: None

Deprecated. No longer used.

class tyro.constructors.StructTypeInfo

Information used to generate constructors for struct types.

type: Type

The type of the (potential) struct.

markers: tuple[Any, Ellipsis]

Markers from tyro.conf that are associated with this field.

default: Any

The default value of the struct, or a member of tyro.constructors.MISSING_AND_MISSING_NONPROP if not present. In a function signature, this is X in def main(x=X): .... This can be useful for populating the default values of the struct.

in_union_context: bool

Flag indicating whether this type is being evaluated as part of a union. When True, allows collection types like List[Struct] or Dict[str, Struct] without defaults to be treated as struct types for subcommand creation.

static make(f: Type | Callable, default: Any, in_union_context: bool) → StructTypeInfo

Parameters:

• f (Type | Callable)

• default (Any)

• in_union_context (bool)

Return type:

StructTypeInfo