Typeshed contains external type annotations for the Python standard library and Python builtins, as well as third party packages as contributed by people external to those projects.

This data can e.g. be used for static analysis, type checking or type inference.

For information on how to use typeshed, read below. Information for contributors can be found in CONTRIBUTING.md. Please read it before submitting pull requests; do not report issues with annotations to the project the stubs are for, but instead report them here to typeshed.

Typeshed supports Python versions 2.7 and 3.6 and up.

If you're just using mypy (or pytype or PyCharm), as opposed to developing it, you don't need to interact with the typeshed repo at all: a copy of standard library part of typeshed is bundled with mypy. And type stubs for third party packages and modules you are using can be installed from PyPI. For example, if you are using six and requests, you can install the type stubs using

$ pip install types-six types-requests

These PyPI packages follow PEP 561 and are automatically generated by typeshed internal machinery. Also starting from version 0.900 mypy will provide an option to automatically install missing type stub packages (if found on PyPI).

PyCharm, pytype etc. work in a similar way, for more details see documentation for the type-checking tool you are using.

Each Python module is represented by a .pyi "stub file". This is a syntactically valid Python file, although it usually cannot be run by Python 3 (since forward references don't require string quotes). All the methods are empty.

Python function annotations (PEP 3107) are used to describe the signature of each function or method.

See PEP 484 for the exact syntax of the stub files and CONTRIBUTING.md for the coding style used in typeshed.

This contains stubs for modules in the Python standard library -- which includes pure Python modules, dynamically loaded extension modules, hard-linked extension modules, and the builtins. The VERSIONS file lists the versions of Python where the module is available.

The structure of the VERSIONS file is as follows:

• Blank lines and lines starting with # are ignored.
• Lines contain the name of a top-level module, followed by a colon, a space, and a version range (for example: symbol: 2.7-3.9).

Version ranges may be of the form "X.Y-A.B" or "X.Y-". The first form means that a module was introduced in version X.Y and last available in version A.B. The second form means that the module was introduced in version X.Y and is still available in the latest version of Python.

Python versions before 2.7 are ignored, so any module that was already present in 2.7 will have "2.7" as its minimum version. Version ranges for unsupported versions of Python 3 (currently 3.5 and lower) are generally accurate but we do not guarantee their correctness.

The stdlib/@python2 subdirectory contains Python 2-only stubs, both for modules that must be kept different for Python 2 and 3, like builtins.pyi, and for modules that only existed in Python 2, like ConfigParser.pyi. The latter group of modules are not listed in VERSIONS.

Note that if a package is present in @python2, any stub in the main stdlib directory should be ignored when looking for Python 2 stubs. For example, typeshed contains files stdlib/@python2/collections.pyi and stdlib/collections/abc.pyi. A client looking for stubs for collections.abc in Python 2 should not pick up the latter file, but instead report that the module does not exist.

Modules that are not shipped with Python but have a type description in Python go into stubs. Each subdirectory there represents a PyPI distribution, and contains the following:

• METADATA.toml that specifies oldest version of the source library for which the stubs are applicable, supported Python versions (Python 3 defaults to True, Python 2 defaults to False), and dependency on other type stub packages.
• Stubs (i.e. *.pyi files) for packages and modules that are shipped in the source distribution. Similar to standard library, if the Python 2 version of the stubs must be kept separate, it can be put in a @python subdirectory.
• (Rarely) some docs specific to a given type stub package in README file.

No other files are allowed in stdlib and stubs. When a third party stub is modified, an updated version of the corresponding distribution will be automatically uploaded to PyPI shortly (within few hours).

For more information on directory structure and stub versioning, see the relevant section of CONTRIBUTING.md.

Third-party packages are generally removed from typeshed when one of the following criteria is met:

• The upstream package ships a py.typed file for at least 6-12 months, or
• the package does not support any of the Python versions supported by typeshed.

Please read CONTRIBUTING.md before submitting pull requests. If you have questions related to contributing, drop by the typing Gitter.

The tests are automatically run on every PR and push to the repo. Therefore you don't need to run them locally, unless you want to run them before making a pull request or you want to debug some problem without creating several small commits.

There are several tests:

• tests/mypy_test.py tests typeshed with mypy
• tests/pytype_test.py tests typeshed with pytype.
• tests/pyright_test.py tests typeshed with pyright.
• tests/mypy_test_suite.py runs a subset of mypy's test suite using this version of typeshed.
• tests/check_consistent.py checks certain files in typeshed remain consistent with each other.
• tests/stubtest_test.py checks stubs against the objects at runtime.
• flake8 enforces a style guide.

Run:

$ python3 -m venv .venv3
$ source .venv3/bin/activate
(.venv3)$ pip install -U pip
(.venv3)$ pip install -r requirements-tests-py3.txt

This will install mypy (you need the latest master branch from GitHub), typed-ast, flake8 (and plugins), pytype, black and isort.

If you want to run the pyright tests, you need to have Node.js installed.

This test requires Python 3.6 or higher; Python 3.6.1 or higher is recommended. Run using:

(.venv3)$ python3 tests/mypy_test.py

This test is shallow — it verifies that all stubs can be imported but doesn't check whether stubs match their implementation (in the Python standard library or a third-party package). It has an exclude list of modules that are not tested at all, which also lives in the tests directory.

You can restrict mypy tests to a single version by passing -p2 or -p3.9:

(.venv3)$ python3 tests/mypy_test.py -p3.9

This test requires Python 2.7 and Python 3.6. Pytype will find these automatically if they're in PATH, but otherwise you must point to them with the --python27-exe and --python36-exe arguments, respectively. Run using:

(.venv3)$ python3 tests/pytype_test.py

This test works similarly to mypy_test.py, except it uses pytype.

This test requires Node.js to be installed. It is currently not part of the CI, but it uses the same pyright version and configuration as the CI.

(.venv3)$ python3 tests/pyright_test.py                 # Check all files
(.venv3)$ python3 tests/pyright_test.py stdlib/sys.pyi  # Check one file

This test requires Python 3.5 or higher; Python 3.6.1 or higher is recommended. Run using:

(.venv3)$ python3 tests/mypy_test_suite.py

This test runs mypy's own test suite using the typeshed code in your repo. This will sometimes catch issues with incorrectly typed stubs, but is much slower than the other tests.

Run using:

python3 tests/check_consistent.py

This test requires Python 3.6 or higher. Run using

(.venv3)$ python3 tests/stubtest_test.py

This test compares the stdlib stubs against the objects at runtime. Because of this, the output depends on which version of Python and on what kind of system it is run. Thus the easiest way to run this test is via Github Actions on your fork; if you run it locally, it'll likely complain about system-specific differences (in e.g, socket) that the type system cannot capture. If you need a specific version of Python to repro a CI failure, pyenv can help.

Due to its dynamic nature, you may run into false positives. In this case, you can add to the whitelists for each affected Python version in tests/stubtest_whitelists. Please file issues for stubtest false positives at mypy.

To run stubtest against third party stubs, it's easiest to use stubtest directly, with

(.venv3)$ python3 -m mypy.stubtest \
  --custom-typeshed-dir <path-to-typeshed> \
  <third-party-module>

stubtest can also help you find things missing from the stubs.

flake8 requires Python 3.6 or higher. Run using:

(.venv3)$ flake8

Note typeshed uses the flake8-pyi and flake8-bugbear plugins.