mirror of
https://github.com/davidhalter/typeshed.git
synced 2026-01-19 01:22:51 +08:00
Rework README and CONTRIBUTING (#5429)
This shuffles sections around between README.md and CONTRIBUTING.md. CONTRIBUTING now contains information pertaining to opening PRs, README all other information. I have also moved the list of maintainers to a separate file. I have kept most information intact for now, with two main exceptions: I removed duplicated information. For brevity's sake, I trimmed some explanations from the section about version checks. I have restructured the CONTRIBUTING file to follow the order of the introductory "contribution process at a glance" section. This now serves as a bit of a table of contents. Closes: #5422
This commit is contained in:
Sebastian Rittau
234
README.md
234
README.md
@@ -38,223 +38,27 @@ 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
|
||||
## Discussion
|
||||
|
||||
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.
|
||||
If you've run into behavior in the type checker that suggests the type
|
||||
stubs for a given library are incorrect or incomplete,
|
||||
we want to hear from you!
|
||||
|
||||
Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/))
|
||||
are used to describe the signature of each function or method.
|
||||
Our main forum for discussion is the project's [GitHub issue
|
||||
tracker](https://github.com/python/typeshed/issues). This is the right
|
||||
place to start a discussion of any of the above or most any other
|
||||
topic concerning the project.
|
||||
|
||||
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.
|
||||
For less formal discussion, try the typing chat room on
|
||||
[gitter.im](https://gitter.im/python/typing). Some typeshed maintainers
|
||||
are almost always present; feel free to find us there and we're happy
|
||||
to chat. Substantive technical discussion will be directed to the
|
||||
issue tracker.
|
||||
|
||||
## Directory structure
|
||||
## Code of Conduct
|
||||
|
||||
### 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. 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.
|
||||
|
||||
### 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.
|
||||
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](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_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.
|
||||
|
||||
You can restrict mypy tests to a single version by passing `-p2` or `-p3.9`:
|
||||
```bash
|
||||
(.venv3)$ python3 tests/mypy_test.py -p3.9
|
||||
```
|
||||
|
||||
### 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. 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
|
||||
```
|
||||
|
||||
### 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.
|
||||
Everyone participating in the typeshed community, and in particular in
|
||||
our issue tracker, pull requests, and Gitter channel, is expected to treat
|
||||
other people with respect and more generally to follow the guidelines
|
||||
articulated in the [Python Community Code of
|
||||
Conduct](https://www.python.org/psf/codeofconduct/).
|
||||
|
||||
Reference in New Issue
Block a user