`_ for all :py:class:`TypedDict` features.
.. code-block:: python
:linenos:
# 04_dictionaries.py
from typing import TypedDict
from typing_extensions import NotRequired
import tyro
class DictionarySchemaA(
TypedDict,
# Setting `total=False` specifies that not all keys need to exist.
total=False,
):
learning_rate: float
betas: tuple[float, float]
class DictionarySchemaB(TypedDict):
learning_rate: NotRequired[float]
"""NotRequired[] specifies that a particular key doesn't need to exist."""
betas: tuple[float, float]
def main(
typed_dict_a: DictionarySchemaA,
typed_dict_b: DictionarySchemaB,
standard_dict: dict[str, float] = {
"learning_rate": 3e-4,
"beta1": 0.9,
"beta2": 0.999,
},
) -> None:
assert isinstance(typed_dict_a, dict)
assert isinstance(typed_dict_b, dict)
assert isinstance(standard_dict, dict)
print("Typed dict A:", typed_dict_a)
print("Typed dict B:", typed_dict_b)
print("Standard dict:", standard_dict)
if __name__ == "__main__":
tyro.cli(main)
.. raw:: html
$ python ./04_dictionaries.py --help
usage: ./04_dictionaries.py [-h] [OPTIONS]
╭─ options ────────────────────────────────────────────────────────────────────╮
│ -h, --help │
│ show this help message and exit │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ typed-dict-a options ───────────────────────────────────────────────────────╮
│ --typed-dict-a.learning-rate FLOAT │
│ (unset by default) │
│ --typed-dict-a.betas FLOAT FLOAT │
│ (unset by default) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ typed-dict-b options ───────────────────────────────────────────────────────╮
│ --typed-dict-b.learning-rate FLOAT │
│ NotRequired[] specifies that a particular key doesn't need to exist. │
│ (unset by default) │
│ --typed-dict-b.betas FLOAT FLOAT │
│ (required) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ standard-dict options ──────────────────────────────────────────────────────╮
│ --standard-dict.learning-rate FLOAT │
│ (default: 0.0003) │
│ --standard-dict.beta1 FLOAT │
│ (default: 0.9) │
│ --standard-dict.beta2 FLOAT │
│ (default: 0.999) │
╰──────────────────────────────────────────────────────────────────────────────╯
.. raw:: html
$ python ./04_dictionaries.py --typed-dict-a.learning-rate 3e-4 --typed-dict-b.betas 0.9 0.999
Typed dict A: {'learning_rate': 0.0003}
Typed dict B: {'betas': (0.9, 0.999)}
Standard dict: {'learning_rate': 0.0003, 'beta1': 0.9, 'beta2': 0.999}
.. raw:: html
$ python ./04_dictionaries.py --typed-dict-b.betas 0.9 0.999
Typed dict A: {}
Typed dict B: {'betas': (0.9, 0.999)}
Standard dict: {'learning_rate': 0.0003, 'beta1': 0.9, 'beta2': 0.999}
.. _example-05_tuples:
Tuples and ``NamedTuple``
-------------------------
Example using :func:`tyro.cli()` to instantiate tuple types. :py:class:`tuple`,
:py:data:`typing.Tuple`, and :py:class:`typing.NamedTuple` are all supported.
.. code-block:: python
:linenos:
# 05_tuples.py
from typing import NamedTuple
import tyro
# Named tuples are interpreted as nested structures.
class Color(NamedTuple):
r: int
g: int
b: int
class TupleType(NamedTuple):
"""Description.
This should show up in the helptext!"""
# Tuple types can contain raw values.
color: tuple[int, int, int] = (255, 0, 0)
# Tuple types can contain nested structures.
two_colors: tuple[Color, Color] = (Color(255, 0, 0), Color(0, 255, 0))
if __name__ == "__main__":
x = tyro.cli(TupleType)
assert isinstance(x, tuple)
print(x)
.. raw:: html
$ python ./05_tuples.py --help
usage: ./05_tuples.py [-h] [OPTIONS]
Description. This should show up in the helptext!
╭─ options ────────────────────────────────────────────────────────────────────╮
│ -h, --help show this help message and exit │
│ --color INT INT INT Tuple types can contain raw values. (default: 255 0 0) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ two-colors.0 options ───────────────────────────────────────────────────────╮
│ --two-colors.0.r INT (default: 255) │
│ --two-colors.0.g INT (default: 0) │
│ --two-colors.0.b INT (default: 0) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ two-colors.1 options ───────────────────────────────────────────────────────╮
│ --two-colors.1.r INT (default: 0) │
│ --two-colors.1.g INT (default: 255) │
│ --two-colors.1.b INT (default: 0) │
╰──────────────────────────────────────────────────────────────────────────────╯
.. raw:: html
$ python ./05_tuples.py --color 127 127 127
TupleType(color=(127, 127, 127), two_colors=(Color(r=255, g=0, b=0), Color(r=0, g=255, b=0)))
.. raw:: html
$ python ./05_tuples.py --two-colors.1.r 127 --two-colors.1.g 0 --two-colors.1.b 0
TupleType(color=(255, 0, 0), two_colors=(Color(r=255, g=0, b=0), Color(r=127, g=0, b=0)))
.. _example-06_pydantic:
Pydantic integration
--------------------
In addition to standard dataclasses, :func:`tyro.cli()` also supports
`Pydantic `_ models.
.. code-block:: python
:linenos:
# 06_pydantic.py
from pydantic import BaseModel, Field
import tyro
class Args(BaseModel):
"""Description.
This should show up in the helptext!"""
field1: str
field2: int = Field(3, description="An integer field.")
if __name__ == "__main__":
args = tyro.cli(Args)
print(args)
.. raw:: html
$ python ./06_pydantic.py --help
usage: ./06_pydantic.py [-h] --field1 STR [--field2 INT]
Description. This should show up in the helptext!
╭─ options ─────────────────────────────────────╮
│ -h, --help show this help message and exit │
│ --field1 STR (required) │
│ --field2 INT An integer field. (default: 3) │
╰───────────────────────────────────────────────╯
.. raw:: html
$ python ./06_pydantic.py --field1 hello
field1='hello' field2=3
.. raw:: html
$ python ./06_pydantic.py --field1 hello --field2 5
field1='hello' field2=5
.. _example-07_attrs:
Attrs integration
-----------------
In addition to standard dataclasses, :func:`tyro.cli()` also supports
`attrs `_ classes.
.. code-block:: python
:linenos:
# 07_attrs.py
import attr
import tyro
@attr.s
class Args:
"""Description.
This should show up in the helptext!"""
field1: str = attr.ib()
"""A string field."""
field2: int = attr.ib(factory=lambda: 5)
"""A required integer field."""
if __name__ == "__main__":
args = tyro.cli(Args)
print(args)
.. raw:: html
$ python ./07_attrs.py --help
usage: ./07_attrs.py [-h] --field1 STR [--field2 INT]
Description. This should show up in the helptext!
╭─ options ────────────────────────────────────────────╮
│ -h, --help show this help message and exit │
│ --field1 STR A string field. (required) │
│ --field2 INT A required integer field. (default: 5) │
╰──────────────────────────────────────────────────────╯
.. raw:: html
$ python ./07_attrs.py --field1 hello
Args(field1='hello', field2=5)
.. raw:: html
$ python ./07_attrs.py --field1 hello --field2 5
Args(field1='hello', field2=5)
.. _example-08_ml_collections:
ML collections
--------------
:func:`tyro.cli` understands and can populate config objects implemented using
`ml_collections `_, which is an
excellent library from folks at Google.
``ml_collections`` structures aren't statically typed, so we infer field types
based on value.
.. code-block:: python
:linenos:
# 08_ml_collections.py
from pprint import pprint
from ml_collections import ConfigDict, FrozenConfigDict # type: ignore
import tyro
def get_config() -> FrozenConfigDict:
config = ConfigDict()
# Wandb config.
config.wandb = ConfigDict()
config.wandb.mode = "online" # online, offline, disabled.
config.wandb.project = "robot-sandbox"
# Network config.
config.network = ConfigDict()
config.network.policy_layer_dims = (128,) * 3
config.network.value_layer_dims = (256,) * 5
config.network.policy_obs_key = "state"
config.network.value_obs_key = "state"
return FrozenConfigDict(config)
def train(config: FrozenConfigDict = get_config()) -> None:
"""Train a model."""
pprint(config.to_dict()) # type: ignore
if __name__ == "__main__":
tyro.cli(train)
.. raw:: html
$ python ./08_ml_collections.py --help
usage: ./08_ml_collections.py [-h] [OPTIONS]
Train a model.
╭─ options ──────────────────────────────────────────╮
│ -h, --help │
│ show this help message and exit │
╰────────────────────────────────────────────────────╯
╭─ config.network options ───────────────────────────╮
│ --config.network.policy-layer-dims [INT [INT ...]] │
│ (default: 128 128 128) │
│ --config.network.policy-obs-key STR │
│ (default: state) │
│ --config.network.value-layer-dims [INT [INT ...]] │
│ (default: 256 256 256 256 256) │
│ --config.network.value-obs-key STR │
│ (default: state) │
╰────────────────────────────────────────────────────╯
╭─ config.wandb options ─────────────────────────────╮
│ --config.wandb.mode STR │
│ (default: online) │
│ --config.wandb.project STR │
│ (default: robot-sandbox) │
╰────────────────────────────────────────────────────╯
.. raw:: html
$ python ./08_ml_collections.py --config.network.policy-layer-dims 64 64 64
{'network': {'policy_layer_dims': (64, 64, 64),
'policy_obs_key': 'state',
'value_layer_dims': (256, 256, 256, 256, 256),
'value_obs_key': 'state'},
'wandb': {'mode': 'online', 'project': 'robot-sandbox'}}
.. _example-09_ml_collections_refs:
ML collections + field references
---------------------------------
``ml_collections`` supports references for sharing values across multiple fields.
.. code-block:: python
:linenos:
# 09_ml_collections_refs.py
from pprint import pprint
from ml_collections import ConfigDict, FieldReference # type: ignore
import tyro
def get_config() -> ConfigDict:
config = ConfigDict()
# Placeholder.
hidden_dim_ref = FieldReference(128)
config.hidden_dim = hidden_dim_ref
# Wandb config.
config.wandb = ConfigDict()
config.wandb.mode = "online" # online, offline, disabled.
config.wandb.project = "robot-sandbox"
# Network config.
# Updating `policy_hidden_dim` will update `value_hidden_dim`, but
# updating `value_hidden_dim` will not update `policy_hidden_dim`.
config.network = ConfigDict()
config.network.policy_hidden_dim = hidden_dim_ref
config.network.value_hidden_dim = hidden_dim_ref * 2
config.network.policy_obs_key = "state"
config.network.value_obs_key = "state"
return config
def train(config: ConfigDict = get_config()) -> None:
"""Train a model."""
pprint(config.to_dict()) # type: ignore
if __name__ == "__main__":
tyro.cli(train)
.. raw:: html
$ python ./09_ml_collections_refs.py --help
usage: ./09_ml_collections_refs.py [-h] [OPTIONS]
Train a model.
╭─ options ─────────────────────────────────────────╮
│ -h, --help │
│ show this help message and exit │
╰───────────────────────────────────────────────────╯
╭─ config options ──────────────────────────────────╮
│ --config.hidden-dim INT │
│ Reference default: 128. (assigns reference) │
╰───────────────────────────────────────────────────╯
╭─ config.network options ──────────────────────────╮
│ --config.network.policy-hidden-dim INT │
│ Reference default: 128. (assigns reference) │
│ --config.network.policy-obs-key STR │
│ (default: state) │
│ --config.network.value-hidden-dim INT │
│ Reference default: 256. (assigns reference) │
│ --config.network.value-obs-key STR │
│ (default: state) │
╰───────────────────────────────────────────────────╯
╭─ config.wandb options ────────────────────────────╮
│ --config.wandb.mode STR │
│ (default: online) │
│ --config.wandb.project STR │
│ (default: robot-sandbox) │
╰───────────────────────────────────────────────────╯
.. raw:: html
$ python ./09_ml_collections_refs.py --config.hidden-dim 32
{'hidden_dim': 32,
'network': {'policy_hidden_dim': 32,
'policy_obs_key': 'state',
'value_hidden_dim': 64,
'value_obs_key': 'state'},
'wandb': {'mode': 'online', 'project': 'robot-sandbox'}}
.. raw:: html
$ python ./09_ml_collections_refs.py --config.network.policy-hidden-dim 64
{'hidden_dim': 64,
'network': {'policy_hidden_dim': 64,
'policy_obs_key': 'state',
'value_hidden_dim': 128,
'value_obs_key': 'state'},
'wandb': {'mode': 'online', 'project': 'robot-sandbox'}}
.. _example-10_msgspec:
Msgspec integration
-------------------
In addition to standard dataclasses, :func:`tyro.cli()` also supports
`msgspec `_ structs.
.. code-block:: python
:linenos:
# 10_msgspec.py
import msgspec
import tyro
class Args(msgspec.Struct):
"""Description.
This should show up in the helptext!"""
field1: str
"""A string field."""
field2: int = 5
"""A required integer field."""
if __name__ == "__main__":
args = tyro.cli(Args)
print(args)
.. raw:: html
$ python ./10_msgspec.py --help
usage: ./10_msgspec.py [-h] --field1 STR [--field2 INT]
Description. This should show up in the helptext!
╭─ options ────────────────────────────────────────────╮
│ -h, --help show this help message and exit │
│ --field1 STR A string field. (required) │
│ --field2 INT A required integer field. (default: 5) │
╰──────────────────────────────────────────────────────╯
.. raw:: html
$ python ./10_msgspec.py --field1 hello
Args(field1='hello', field2=5)
.. raw:: html
$ python ./10_msgspec.py --field1 hello --field2 5
Args(field1='hello', field2=5)