mirror of
https://github.com/davidhalter/typeshed.git
synced 2025-12-10 05:51:52 +08:00
222 lines
8.8 KiB
Markdown
222 lines
8.8 KiB
Markdown
# typeshed
|
|
|
|
[](https://github.com/python/typeshed/actions?query=workflow%3A%22Check+stubs%22)
|
|
[](https://gitter.im/python/typing?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
|
[](https://github.com/python/typeshed/blob/master/CONTRIBUTING.md)
|
|
|
|
## About
|
|
|
|
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](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.
|
|
|
|
## Using
|
|
|
|
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](http://www.python.org/dev/peps/pep-0561/)
|
|
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.
|
|
|
|
## Format
|
|
|
|
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](https://www.python.org/dev/peps/pep-3107/))
|
|
are used to describe the signature of each function or method.
|
|
|
|
See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact
|
|
syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the
|
|
coding style used in typeshed.
|
|
|
|
## Directory structure
|
|
|
|
### stdlib
|
|
|
|
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. `VERSIONS` file lists
|
|
the oldest *supported* Python version where the module is available.
|
|
In the `stdlib/@python2` subdirectory you can find Python 2 versions of
|
|
the stub files that must be kept different for Python 2 and 3, like
|
|
`builtins.pyi`.
|
|
|
|
### stubs
|
|
|
|
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](
|
|
https://github.com/python/typeshed/blob/master/CONTRIBUTING.md#stub-versioning).
|
|
|
|
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.
|
|
|
|
## Contributing
|
|
|
|
Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests.
|
|
If you have questions related to contributing, drop by the [typing Gitter](https://gitter.im/python/typing).
|
|
|
|
## Running the tests
|
|
|
|
The tests are automatically run on every PR and push to
|
|
the repo.
|
|
|
|
There are several tests:
|
|
- `tests/mypy_test.py`
|
|
tests typeshed with [mypy](https://github.com/python/mypy/)
|
|
- `tests/pytype_test.py` tests typeshed with
|
|
[pytype](https://github.com/google/pytype/).
|
|
- `tests/pyright_test.py` tests typeshed with
|
|
[pyright](https://github.com/microsoft/pyright).
|
|
- `tests/mypy_self_check.py` checks mypy's code base using this version of
|
|
typeshed.
|
|
- `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.
|
|
|
|
### Setup
|
|
|
|
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](https://nodejs.org/) installed.
|
|
|
|
### mypy_test.py
|
|
|
|
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.
|
|
|
|
If you are in the typeshed repo that is submodule of the
|
|
mypy repo (so `..` refers to the mypy repo), there's a shortcut to run
|
|
the mypy tests that avoids installing mypy:
|
|
```bash
|
|
$ PYTHONPATH=../.. python3 tests/mypy_test.py
|
|
```
|
|
You can restrict mypy tests to a single version by passing `-p2` or `-p3.9`:
|
|
```bash
|
|
$ PYTHONPATH=../.. python3 tests/mypy_test.py -p3.9
|
|
running mypy --python-version 3.9 --strict-optional # with 342 files
|
|
```
|
|
|
|
### pytype_test.py
|
|
|
|
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`.
|
|
|
|
### pyright\_test.py
|
|
|
|
This test requires Node.js to be installed.
|
|
|
|
### mypy_self_check.py
|
|
|
|
This test requires Python 3.6 or higher; Python 3.6.1 or higher is recommended.
|
|
Run using: `(.venv3)$ python3 tests/mypy_self_check.py`
|
|
|
|
This test checks mypy's code base using mypy and typeshed code in this repo.
|
|
|
|
### mypy_test_suite.py
|
|
|
|
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.
|
|
|
|
### check_consistent.py
|
|
|
|
Run using: `python3 tests/check_consistent.py`
|
|
|
|
### stubtest_test.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](https://github.com/pyenv/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](https://github.com/python/mypy/issues).
|
|
|
|
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
|
|
|
|
flake8 requires Python 3.6 or higher. Run using: `(.venv3)$ flake8`
|
|
|
|
Note typeshed uses the `flake8-pyi` and `flake8-bugbear` plugins.
|