RightTyper

RightTyper is a Python tool that generates types for your function arguments and return values. RightTyper lets your code run at nearly full speed (around 30% overhead) and little memory overhead. As a result, you won't experience slowdowns in your code or large memory consumption while using it, allowing you to integrate it with your standard tests and development process. By virtue of its design, and in a significant departure from previous approaches, RightTyper only captures the most commonly used types, letting a type checker like mypy detect possibly incorrect type mismatches in your code.

You can run RightTyper with arbitrary Python programs and it will generate types for every function that gets executed. It works great in combination with pytest:

python3 -m righttyper run -m pytest --continue-on-collection-errors /your/test/dir

In addition to generating types, RightTyper has the following features:

• It efficiently computes type annotation "coverage" for a file or directory of files
• It infers shape annotations for NumPy/JAX/PyTorch tensors, compatible with jaxtyping and beartype or typeguard.

For details about how RightTyper works, please see the following paper: RightTyper: Effective and Efficient Type Annotation for Python.

Performance Comparison

The graph below presents the overhead of using RightTyper versus two previous tools, PyAnnotate and MonkeyType, across a range of benchmarks. On average, RightTyper imposes only 30% overhead compared to running plain Python. On running the tests of a popular package (black), RightTyper imposes only 20% overhead, while MonkeyType slows down execution by over 6x. In extreme cases, MonkeyType runs over 270x slower than RightTyper.

Usage

Install RightTyper from pip as usual:

python3 -m pip install righttyper

To use RightTyper, simply run your script with python3 -m righttyper run instead of python3:

python3 -m righttyper run your_script.py [args...]

This will execute your_script.py with RightTyper's monitoring enabled. The type signatures of all functions will be recorded and output to a file named righttyper.out. The file contains, for every function, the signature, and a diff of the original function with the annotated version. It also optionally (with the --infer-shapes flag) generates jaxtyping-compatible shape annotations for NumPy/JAX/PyTorch tensors. Below is an example:

test-hints.py:
==============

barnacle

- def barnacle(x):
+ def barnacle(x: jaxtyping.Float64[np.ndarray, "10 D1"]) -> jaxtyping.Float64[np.ndarray, "D1"]:

fooq

- def fooq(x: int, y) -> bool:
+ def fooq(x: int, y: int) -> bool:
?                   +++++

To add type hints directly to your code, use this command:

python3 -m righttyper run --output-files --overwrite your_script.py [args...]

To do the same with pytest:

python3 -m righttyper run --output-files --overwrite -m pytest [pytest-args...]

Below is the full list of options for the run command:

$ python3.12 -m righttyper run --help
Usage: python -m righttyper run [OPTIONS] [SCRIPT] [ARGS]...

  Runs a given script or module, collecting type information.

Options:
  -m, --module MODULE             Run the given module instead of a script.
  --all-files                     Process any files encountered, including
                                  libraries (except for those specified in
                                  --include-files)
  --include-files TEXT            Process only files matching the given
                                  pattern.
  --include-functions TEXT        Only annotate functions matching the given
                                  pattern.
  --infer-shapes                  Produce tensor shape annotations (compatible
                                  with jaxtyping).
  --root DIRECTORY                Process only files under the given
                                  directory.  If omitted, the script's
                                  directory (or, for -m, the current
                                  directory) is used.
  --overwrite / --no-overwrite    Overwrite files with type information.
                                  [default: no-overwrite]
  --output-files / --no-output-files
                                  Output annotated files (possibly
                                  overwriting, if specified).  [default: no-
                                  output-files]
  --ignore-annotations            Ignore existing annotations and overwrite
                                  with type information.
  --only-update-annotations       Overwrite existing annotations but never add
                                  new ones.
  --generate-stubs                Generate stub files (.pyi).
  --target-overhead FLOAT         Target overhead, as a percentage (e.g., 5).
                                  [default: 5.0]
  --use-multiprocessing / --no-use-multiprocessing
                                  Whether to use multiprocessing.  [default:
                                  use-multiprocessing]
  --sampling / --no-sampling      Whether to sample calls or to use every one.
                                  [default: sampling]
  --replace-dict / --no-replace-dict
                                  Whether to replace 'dict' to enable
                                  efficient, statistically correct samples.
                                  [default: no-replace-dict]
  --container-sample-limit INTEGER
                                  Number of container elements to sample.
                                  [default: 1000]
  --python-version [3.9|3.10|3.11|3.12|3.13]
                                  Python version for which to emit
                                  annotations.  [default: 3.12]
  --use-top-pct INTEGER RANGE     Only use the X% most common call traces.
                                  [default: 80; 1<=x<=100]
  --only-collect                  Rather than immediately process collect
                                  data, save it to righttyper.rt. You can
                                  later process using RightTyper's "process"
                                  command.
  --help                          Show this message and exit.