Python type inferencer
Project description
pytype - 🦆✔
Pytype checks and infers types for your Python code - without requiring type annotations. Pytype can:
- Lint plain Python code, flagging common mistakes such as misspelled attribute names, incorrect function calls, and much more, even across file boundaries.
- Enforce user-provided type annotations. While annotations are optional for pytype, it will check and apply them where present.
- Generate type annotations in standalone files ("pyi files"), which can be merged back into the Python source with a provided merge-pyi tool.
Pytype is a static analyzer; it does not execute the code it runs on.
Thousands of projects at Google rely on pytype to keep their Python code well-typed and error-free.
For more information, check out the user guide, FAQ, or supported features.
How is pytype different from other type checkers?
-
Pytype uses inference instead of gradual typing. This means it will infer types on code even when the code has no type hints on it. So it can detect issues with code like this, which other type checkers would miss:
def f(): return "PyCon" def g(): return f() + 2019 # pytype: line 4, in g: unsupported operand type(s) for +: 'str' # and 'int' [unsupported-operands]
-
Pytype is lenient instead of strict. That means it allows all operations that succeed at runtime and don't contradict annotations. For instance, this code will pass as safe in pytype, but fail in other type checkers, which assign types to variables as soon as they are initialized:
from typing import List def get_list() -> List[str]: lst = ["PyCon"] lst.append(2019) return [str(x) for x in lst] # mypy: line 4: error: Argument 1 to "append" of "list" has # incompatible type "int"; expected "str"
Also see the corresponding FAQ entry.
Quickstart
To quickly get started with type-checking a file or directory, run the
following, replacing file_or_directory
with your input:
pip install pytype
pytype file_or_directory
To set up pytype on an entire package, add the following to a pyproject.toml
file in the directory immediately above the package, replacing package_name
with the package name:
[tool.pytype]
inputs = ['package_name']
Now you can run the no-argument command pytype
to type-check the package. It's
also easy to add pytype to your automated testing; see this
example of a GitHub project that runs pytype on GitHub Actions.
Finally, pytype generates files of inferred type information, located by default
in .pytype/pyi
. You can use this information to type-annotate the
corresponding source file:
merge-pyi -i <filepath>.py .pytype/pyi/<filename>.pyi
Requirements
You need a Python 3.8-3.12 interpreter to run pytype, as well as an
interpreter in $PATH
for the Python version of the code you're analyzing
(supported: 3.8-3.12).
Platform support:
- Pytype is currently developed and tested on Linux*, which is the main supported platform.
- Installation on MacOSX requires OSX 10.7 or higher and Xcode v8 or higher**.
- Windows is currently not supported unless you use WSL.
*
On Alpine Linux, installation may fail due to issues with upstream
dependencies. See the details of this issue for a
possible fix.
**
If the ninja dependency fails to install, make sure cmake is installed. See
this issue for details.
Installing
Pytype can be installed via pip. Note that the installation requires wheel
and setuptools
. (If you're working in a virtualenv, these two packages should
already be present.)
pip install pytype
Or from the source code on GitHub.
git clone --recurse-submodules https://github.com/google/pytype.git
cd pytype
pip install .
Instead of using --recurse-submodules
, you could also have run
git submodule init
git submodule update
in the pytype
directory. To edit the code and have your edits tracked live,
replace the pip install command with:
pip install -e .
Installing on WSL
Follow the steps above, but make sure you have the correct libraries first:
sudo apt install build-essential python3-dev libpython3-dev
Usage
usage: pytype [options] input [input ...]
positional arguments:
input file or directory to process
Common options:
-V, --python-version
: Python version (major.minor) of the target code. Defaults to the version that pytype is running under.-o, --output
: The directory into which all pytype output goes, including generated .pyi files. Defaults to.pytype
.-d, --disable
. Comma or space-separated list of error names to ignore. Detailed explanations of pytype's error names are in this doc. Defaults to empty.
For a full list of options, run pytype --help
.
In addition to the above, you can direct pytype to use a custom typeshed
installation instead of its own bundled copy by setting $TYPESHED_HOME
.
Config File
For convenience, you can save your pytype configuration in a file. The config
file can be a TOML-style file with a [tool.pytype]
section (preferred) or an
INI-style file with a [pytype]
section. If an explicit config file is not
supplied, pytype will look for a pytype section in the first pyproject.toml
or
setup.cfg
file found by walking upwards from the current working directory.
Start off by generating a sample config file:
$ pytype --generate-config pytype.toml
Now customize the file based on your local setup, keeping only the sections you need. Directories may be relative to the location of the config file, which is useful if you want to check in the config file as part of your project.
For example, suppose you have the following directory structure and want to
analyze package ~/repo1/foo
, which depends on package ~/repo2/bar
:
~/
├── repo1
│ └── foo
│ ├── __init__.py
│ └── file_to_check.py
└── repo2
└── bar
├── __init__.py
└── dependency.py
Here is the filled-in config file, which instructs pytype to type-check
~/repo1/foo
as Python 3.9 code, look for packages in ~/repo1
and ~/repo2
,
and ignore attribute errors. Notice that the path to a package does not include
the package itself.
$ cat ~/repo1/pytype.toml
# NOTE: All relative paths are relative to the location of this file.
[tool.pytype]
# Space-separated list of files or directories to process.
inputs = [
'foo',
]
# Python version (major.minor) of the target code.
python_version = '3.9'
# Paths to source code directories, separated by ':'.
pythonpath = .:~/repo2
# Space-separated list of error names to ignore.
disable = [
'attribute-error',
]
We could've discovered that ~/repo2
needed to be added to the pythonpath by
running pytype's broken dependency checker:
$ pytype --config=~/repo1/pytype.toml ~/repo1/foo/*.py --unresolved
Unresolved dependencies:
bar.dependency
Subtools
Pytype ships with a few scripts in addition to pytype
itself:
annotate-ast
, an in-progress type annotator for ASTs.merge-pyi
, for merging type information from a .pyi file into a Python file.pytd-tool
, a parser for .pyi files.pytype-single
, a debugging tool for pytype developers, which analyzes a single Python file assuming that .pyi files have already been generated for all of its dependencies.pyxref
, a cross-references generator.
License
Disclaimer
This is not an official Google product.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for pytype-2024.10.11-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fb98711679e631b01b09b09185504fbf38d60f119280918e244a602cf843b0fe |
|
MD5 | a3c8ffcb72721414d8f2fe49d3c93bcb |
|
BLAKE2b-256 | 201052422fdb5a6b4a04938f47a76c655325775b7dd8cc71bd3557aae87b40e1 |
Hashes for pytype-2024.10.11-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 13327d0d17b981fe2660dd3a69f97bf09a526f93debc40bb44b240628e0b55c1 |
|
MD5 | 02022e83e7fbcb490130bf6358b97999 |
|
BLAKE2b-256 | 04515925fe8992f02adab358ce9e8068defdae1e58393bfd767e035509da9872 |
Hashes for pytype-2024.10.11-cp312-cp312-macosx_10_14_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cdc881cce9541a475ec48989a5ab889e6274a85afbf6da0e30266d0823f66d42 |
|
MD5 | 42c7012727f09b259271ee38c9d54810 |
|
BLAKE2b-256 | 78a2cf47d02d846f6d837e1023b2c19588127c4d9dfc577b8eceb4870def32f4 |
Hashes for pytype-2024.10.11-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ead3408fc9622ba8a357c9a6b9b49059a9b8add0a3b8390a9ab490f62a984005 |
|
MD5 | 3f675b006a4721aea8f5b743aee52738 |
|
BLAKE2b-256 | faa97e3776a0ae4fcdb988c013384c92a0e716f1e896c2c0012f446ba932093c |
Hashes for pytype-2024.10.11-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 15e2f39590cc08ef8e6704cfa5c1db6fbbee2799891f9d8adbf821f883a54745 |
|
MD5 | 7b32fe60b6f715a6c6d172e90ba7b0ad |
|
BLAKE2b-256 | ed03406255d17ba64acd8c48e8eeba95276084d70dd2e9b92a88bd6ebd013efe |
Hashes for pytype-2024.10.11-cp311-cp311-macosx_10_14_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2e31a964aa82e1ac317adbe17b77010e4f362882df1ce7ad15ef0cf0bb97039f |
|
MD5 | dfaa5e86b1ac7cdba823326ec974f12e |
|
BLAKE2b-256 | 23115e31c16d022b724798567e85e313563a78625d7c28247ba0c8ec2741d3e2 |
Hashes for pytype-2024.10.11-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 37d8dfdf23679abfdfe047efef7239a438a038e580d7e0767c0403a6be07cea0 |
|
MD5 | 04254bdaacdabe17df4cbe49d8d34fdd |
|
BLAKE2b-256 | 2665d3b61acd71e96dab8c332bb43f8e7f26251c960b621f86e14a5ffaf35d2f |
Hashes for pytype-2024.10.11-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5dd9ecb48aa46ecef14b39f1bbe8ff7e586e499639a056c05bd4436ca0b35d82 |
|
MD5 | 504248b7b550608642028022c7228206 |
|
BLAKE2b-256 | dece94f2973a61f3937c161842b9f0a32477c7084f4ee1fe2814d6b2678f4e98 |
Hashes for pytype-2024.10.11-cp310-cp310-macosx_12_0_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1c5a43b132b19928a38ba1dbcf8f4e3f67a41ea26087ccf26ae371c4076c3809 |
|
MD5 | 8ca1e9ce0ef1fefa5ac1c47a08618f33 |
|
BLAKE2b-256 | 2218ae46cb01ff6c95bfef5bb2a8a9e089dff537972999a02d9ee7674c98de7b |