https://github.com/RightTyper/RightTyper
A fast and efficient type assistant for Python, including tensor shape inference
https://github.com/RightTyper/RightTyper
python typing
Last synced: 2 months ago
JSON representation
A fast and efficient type assistant for Python, including tensor shape inference
- Host: GitHub
- URL: https://github.com/RightTyper/RightTyper
- Owner: RightTyper
- License: apache-2.0
- Created: 2024-07-31T23:28:14.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-25T20:05:19.000Z (2 months ago)
- Last Synced: 2025-08-25T22:08:33.857Z (2 months ago)
- Topics: python, typing
- Language: Python
- Homepage:
- Size: 1.19 MB
- Stars: 331
- Watchers: 3
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
- trackawesomelist - RightTyper (⭐154) - A tool that generates types for your function arguments and return values. RightTyper lets your code run at nearly full speed with almost no memory overhead. (Recently Updated / [Dec 24, 2024](/content/2024/12/24/README.md))
- awesome-python-typing - RightTyper - A tool that generates types for your function arguments and return values. RightTyper lets your code run at nearly full speed with almost no memory overhead. (Tools / Helper tools to add annotations to existing code)
README
# RightTyper
[](https://pypi.org/project/righttyper/)
[](https://pepy.tech/project/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](https://docs.pytest.org/):
```bash
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`](https://docs.kidger.site/jaxtyping/) and [`beartype`](https://github.com/beartype/beartype) or [`typeguard`](https://typeguard.readthedocs.io/en/latest/).
For details about how RightTyper works, please see the following paper: **[RightTyper: Effective and Efficient Type Annotation for Python](https://www.arxiv.org/abs/2507.16051)**.
## 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:
```bash
python3 -m pip install righttyper
```
To use RightTyper, simply run your script with `python3 -m righttyper run` instead of `python3`:
```bash
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:
```diff
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:
```bash
python3 -m righttyper run --output-files --overwrite your_script.py [args...]
```
To do the same with `pytest`:
```bash
python3 -m righttyper run --output-files --overwrite -m pytest [pytest-args...]
```
### Type ergonomics
RightTyper may infer types that include deeply nested generics.
While such precise types improve recall in type checking, they can be difficult for developers to read and understand.
To improve the ergonomics of such annotations, RightTyper offers a `--type-depth-limit` option to specify the maximum
number of levels to include in type.
For example, with `--type-depth-limit=1`, a type inferred as `list[tuple[tuple[int, int]]]` would be emitted as `list[tuple]` instead.
### Option overview
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 PATTERN Process only files matching the given
pattern.
--include-functions PATTERN 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).
--json-output Output inferences in JSON, instead of
writing righttyper.out.
--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]
--type-depth-limit [INTEGER|none]
Maximum depth (types within types) for
generic types; 'none' to disable. [default:
none]
--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 PCT Only use the PCT% 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.
--exclude-types TYPE_NAME Exclude or replace with "typing.Any" types
whose full name starts with the given
string. Can be passed multiple times.
[default: pytest., _pytest., py.test.,
test_]
--no-exclude-types Do not exclude types.
--resolve-mocks TYPE_NAME Attempt to resolve mock types whose full
name starts with the given string to non-
test types. Can be passed multiple times.
[default: test_, unittest.mock.]
--no-resolve-mocks Do not attempt to resolve mock types.
--use-typing-never / --no-use-typing-never
Whether to emit typing.Never. [default:
use-typing-never]
--help Show this message and exit.
```