Skip to main content

Strongly typed, zero-effort CLI interfaces

Project description


tyro logo

Documentation   •   pip install tyro

build mypy lint codecov codecov


tyro is a tool for building command-line interfaces and configuration objects in Python.

Our core interface, tyro.cli(), generates command-line interfaces from type-annotated callables.


Brief walkthrough

To summarize how tyro.cli() can be used, let's consider a script based on argparse. We define two inputs and print the sum:

"""Sum two numbers from argparse."""
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--a", type=int, required=True)
parser.add_argument("--b", type=int, default=3)
args = parser.parse_args()

total = args.a + args.b

print(total)

This pattern is dramatically cleaner than manually parsing sys.argv, but has several issues: it lacks type checking and IDE support (consider: jumping to definitions, finding references, docstrings, refactoring and renaming tools), requires a significant amount of parsing-specific boilerplate, and becomes difficult to manage for larger projects.

The basic goal of tyro.cli() is to provide a wrapper for argparse that solves these issues.

(1) Command-line interfaces from functions.

We can write the same script as above using tyro.cli():

"""Sum two numbers by calling a function with tyro."""
import tyro

def add(a: int, b: int = 3) -> int:
    return a + b

# Populate the inputs of add(), call it, then return the output.
total = tyro.cli(add)

print(total)

Or, more succinctly:

"""Sum two numbers by calling a function with tyro."""
import tyro

def add(a: int, b: int = 3) -> None:
    print(a + b)

tyro.cli(add)  # Returns `None`.

(2) Command-line interfaces from config objects.

A class in Python can be treated as a function that returns an instance. This makes it easy to populate explicit configuration structures:

"""Sum two numbers by instantiating a dataclass with tyro."""
from dataclasses import dataclass

import tyro

@dataclass
class Args:
    a: int
    b: int = 3

args = tyro.cli(Args)
print(args.a + args.b)

Unlike directly using argparse, both the function-based and dataclass-based approaches are compatible with static analysis; tab completion and type checking will work out-of-the-box.

(3) Additional features.

These examples only scratch the surface of what's possible. tyro aims to support all reasonable type annotations, which can help us define things like hierachical structures, enums, unions, variable-length inputs, and subcommands. See documentation for examples.

In the wild

tyro is still a new library, but being stress tested in several projects!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tyro-0.4.2.tar.gz (52.2 kB view details)

Uploaded Source

Built Distribution

tyro-0.4.2-py3-none-any.whl (61.1 kB view details)

Uploaded Python 3

File details

Details for the file tyro-0.4.2.tar.gz.

File metadata

  • Download URL: tyro-0.4.2.tar.gz
  • Upload date:
  • Size: 52.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.0 CPython/3.8.16 Linux/5.15.0-1034-azure

File hashes

Hashes for tyro-0.4.2.tar.gz
Algorithm Hash digest
SHA256 f14685b3f98cb1028e3a2b92a4dae9be4440d189970ea4e2ec820ddd357f4e2e
MD5 cd44b8974c4115da97ed61d4ccdfb5c5
BLAKE2b-256 0a7e2278fc9f17140c33d80b6d1c5b1d95fc69deab438e350ccce052e5b51dca

See more details on using hashes here.

File details

Details for the file tyro-0.4.2-py3-none-any.whl.

File metadata

  • Download URL: tyro-0.4.2-py3-none-any.whl
  • Upload date:
  • Size: 61.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.4.0 CPython/3.8.16 Linux/5.15.0-1034-azure

File hashes

Hashes for tyro-0.4.2-py3-none-any.whl
Algorithm Hash digest
SHA256 f7accb999690aaa4f5e14ff7268cdee051b018cd01c7ac9ed401ed90ed9704dd
MD5 3c8e3cd25d97c3f5ccdeacc45d8568da
BLAKE2b-256 7d47bdf57b434a5a400a3d384fcbfb4bf92eced1e08746a9a9be8a03f8c48dd6

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page