.. Comment: this file is automatically generated by `update_example_docs.py`.
   It should not be modified manually.

.. _example-category-generics:

Generics
========

:mod:`tyro`'s understanding of Python's type system includes user-defined
parameterized types, which can reduce boilerplate and improve type safety.


.. _example-01_generics_py312:

Generics (3.12+)
----------------

This example uses syntax introduced in Python 3.12 (`PEP 695 <https://peps.python.org/pep-0695/>`_).

.. note::

    If used in conjunction with :code:`from __future__ import annotations`, the updated type parameter syntax requires Python 3.12.4 or newer. For technical details, see `this CPython PR <https://github.com/python/cpython/pull/118009>`_.


.. code-block:: python
    :linenos:

    # 01_generics_py312.py
    import dataclasses

    import tyro

    @dataclasses.dataclass
    class Point3[ScalarType: (int, float)]:
        x: ScalarType
        y: ScalarType
        z: ScalarType
        frame_id: str

    @dataclasses.dataclass
    class Triangle:
        a: Point3[float]
        b: Point3[float]
        c: Point3[float]

    @dataclasses.dataclass
    class Args[ShapeType]:
        shape: ShapeType

    if __name__ == "__main__":
        args = tyro.cli(Args[Triangle])
        print(args)




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./01_generics_py312.py --help</strong>
    <span style="font-weight: bold">usage</span>: 01_generics_py312.py [-h] [OPTIONS]
    
    <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> options </span><span style="font-weight: lighter">──────────────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
    <span style="font-weight: lighter">│</span> -h, --help              <span style="font-weight: lighter">show this help message and exit</span> <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">╰─────────────────────────────────────────────────────────╯</span>
    <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> shape.a options </span><span style="font-weight: lighter">──────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
    <span style="font-weight: lighter">│</span> --shape.a.x <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.a.y <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.a.z <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.a.frame-id <span style="font-weight: bold">STR</span>  <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">╰─────────────────────────────────────────────────────────╯</span>
    <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> shape.b options </span><span style="font-weight: lighter">──────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
    <span style="font-weight: lighter">│</span> --shape.b.x <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.b.y <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.b.z <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.b.frame-id <span style="font-weight: bold">STR</span>  <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">╰─────────────────────────────────────────────────────────╯</span>
    <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> shape.c options </span><span style="font-weight: lighter">──────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
    <span style="font-weight: lighter">│</span> --shape.c.x <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.c.y <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.c.z <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.c.frame-id <span style="font-weight: bold">STR</span>  <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">╰─────────────────────────────────────────────────────────╯</span>
    </pre>
.. _example-02_generics:

Generics (Legacy)
-----------------

The legacy :py:class:`typing.Generic` and :py:class:`typing.TypeVar` syntax for
generic types is also supported.


.. code-block:: python
    :linenos:

    # 02_generics.py
    import dataclasses
    from typing import Generic, TypeVar

    import tyro

    ScalarType = TypeVar("ScalarType", int, float)
    ShapeType = TypeVar("ShapeType")

    @dataclasses.dataclass(frozen=True)
    class Point3(Generic[ScalarType]):
        x: ScalarType
        y: ScalarType
        z: ScalarType
        frame_id: str

    @dataclasses.dataclass(frozen=True)
    class Triangle:
        a: Point3[float]
        b: Point3[float]
        c: Point3[float]

    @dataclasses.dataclass(frozen=True)
    class Args(Generic[ShapeType]):
        shape: ShapeType

    if __name__ == "__main__":
        args = tyro.cli(Args[Triangle])
        print(args)




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./02_generics.py --help</strong>
    <span style="font-weight: bold">usage</span>: 02_generics.py [-h] [OPTIONS]
    
    <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> options </span><span style="font-weight: lighter">──────────────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
    <span style="font-weight: lighter">│</span> -h, --help              <span style="font-weight: lighter">show this help message and exit</span> <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">╰─────────────────────────────────────────────────────────╯</span>
    <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> shape.a options </span><span style="font-weight: lighter">──────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
    <span style="font-weight: lighter">│</span> --shape.a.x <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.a.y <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.a.z <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.a.frame-id <span style="font-weight: bold">STR</span>  <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">╰─────────────────────────────────────────────────────────╯</span>
    <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> shape.b options </span><span style="font-weight: lighter">──────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
    <span style="font-weight: lighter">│</span> --shape.b.x <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.b.y <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.b.z <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.b.frame-id <span style="font-weight: bold">STR</span>  <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">╰─────────────────────────────────────────────────────────╯</span>
    <span style="font-weight: lighter">╭─</span><span style="font-weight: lighter"> shape.c options </span><span style="font-weight: lighter">──────────────────────────────────────</span><span style="font-weight: lighter">─╮</span>
    <span style="font-weight: lighter">│</span> --shape.c.x <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.c.y <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.c.z <span style="font-weight: bold">FLOAT</span>       <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">│</span> --shape.c.frame-id <span style="font-weight: bold">STR</span>  <span style="font-weight: bold; color: #e60000">(required)</span>                      <span style="font-weight: lighter">│</span>
    <span style="font-weight: lighter">╰─────────────────────────────────────────────────────────╯</span>
    </pre>