Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/brentyi/tyro

CLI interfaces & config objects, from types
https://github.com/brentyi/tyro

argparse argument-parsing dataclasses

Last synced: 7 days ago
JSON representation

CLI interfaces & config objects, from types

Awesome Lists containing this project

README

        









tyro logo



Documentation
  •  
pip install tyro



mypy
pyright


codecov


codecov


tyro.cli() is a tool for generating CLI
interfaces from type-annotated Python.

We can define configurable scripts using functions:

```python
"""A command-line interface defined using a function signature.

Usage: python script_name.py --foo INT [--bar STR]
"""

import tyro

def main(
foo: int,
bar: str = "default",
) -> None:
... # Main body of a script.

if __name__ == "__main__":
# Generate a CLI and call `main` with its two arguments: `foo` and `bar`.
tyro.cli(main)
```

Or instantiate config objects defined using tools like `dataclasses`, `pydantic`, and `attrs`:

```python
"""A command-line interface defined using a class signature.

Usage: python script_name.py --foo INT [--bar STR]
"""

from dataclasses import dataclass
import tyro

@dataclass
class Config:
foo: int
bar: str = "default"

if __name__ == "__main__":
# Generate a CLI and instantiate `Config` with its two arguments: `foo` and `bar`.
config = tyro.cli(Config)

# Rest of script.
assert isinstance(config, Config) # Should pass.
```

Other features include helptext generation, nested structures, subcommands, and
shell completion. For examples and the API reference, see our
[documentation](https://brentyi.github.io/tyro).

### Why `tyro`?

1. **Define things once.** Standard Python type annotations, docstrings, and default values are parsed to automatically generate command-line interfaces with informative helptext.

2. **Static types.** Unlike tools dependent on dictionaries, YAML, or dynamic
namespaces, arguments populated by `tyro` benefit from IDE and language
server-supported operations — tab completion, rename, jump-to-def,
docstrings on hover — as well as static checking tools like `pyright` and
`mypy`.

3. **Modularity.** `tyro` supports hierarchical configuration structures, which
make it easy to decentralize definitions, defaults, and documentation.

### In the wild

`tyro` is designed to be lightweight enough for throwaway scripts, while
facilitating type safety and modularity for larger projects. Examples:




nerfstudio-project/nerfstudio

GitHub star count



Open-source tools for neural radiance fields.





Sea-Snell/JAXSeq

GitHub star count


Train very large language models in Jax.




kevinzakka/obj2mjcf

GitHub star count


Interface for processing OBJ files for Mujoco.




blurgyy/jaxngp

GitHub star count



CUDA-accelerated implementation of
instant-ngp, in JAX.





NVIDIAGameWorks/kaolin-wisp

GitHub star count


PyTorch library for neural fields.




autonomousvision/sdfstudio

GitHub star count


Unified framework for surface reconstruction.




openrlbenchmark/openrlbenchmark

GitHub star count


Collection of tracked experiments for reinforcement learning.




vwxyzjn/cleanrl

GitHub star count


Single-file implementation of deep RL algorithms.

### Alternatives

`tyro` is an opinionated library. If any design decisions don't make sense,
feel free to file an issue!

You might also consider one of many alternative libraries. Some that we
particularly like:

- [simple-parsing](https://github.com/lebrice/SimpleParsing) and
[jsonargparse](https://github.com/omni-us/jsonargparse), which provide deeper
integration with configuration file formats like YAML and JSON.
- [clipstick](https://github.com/sander76/clipstick), which focuses on
simplicity + generating CLIs from Pydantic models.
- [datargs](https://github.com/roee30/datargs), which provides a minimal API for
dataclasses.
- [defopt](https://defopt.readthedocs.io/), which has similarly comprehensive type annotation support.
- [fire](https://github.com/google/python-fire) and
[clize](https://github.com/epsy/clize), which support arguments without type
annotations.

We also have some notes on `tyro`'s design goals and other alternatives in the
docs [here](https://brentyi.github.io/tyro/goals_and_alternatives/).