Skip to content

Suggest splitting Python 2 stubs #5189

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
srittau merged 1 commit into from
Apr 8, 2021
Merged

Suggest splitting Python 2 stubs #5189

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 7 additions & 12 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -307,12 +307,14 @@ There are separate directories for `stdlib` (standard library) and `stubs`
(all other stubs). For standard library stubs Python version support is
given in `VERSIONS` file. Each line in this file is a module or package name
followed by `: `, followed by the oldest *supported* Python version where
the module is available. For third party packages, the Python version support
(2 and/or 3 only, no finer grained version is supported) is indicated in the
corresponding `METADATA.toml` file as `python2 = (True|False)` (defaults to
`False`) and `python3 = (True|False)` (defaults to `True`).
the module is available.

It is preferred to use a single stub for every module. You can use checks
Third-party stubs only support Python 3 by default. You can optionally supply
Python 2 stubs for a package by placing them into a `@python2` subdirectory
for the corresponding distribution. Some older stubs also indicate Python 2
support by setting `python2 = True` in the corresponding `METADATA.toml` file.

You can use checks
like `if sys.version_info >= (3, 8):` to denote new functionality introduced
in a given Python version or solve type differences. When doing so, only use
one-tuples or two-tuples. This is because:
Expand All @@ -337,13 +339,6 @@ harmless. This is a strictly better compromise than using the latter
two forms, which would generate false positive errors for correct use
under Python 3.7.4.

If it is not possible to generate combined stubs for all Python versions
in a single file, you can split Python 2 and Python 3 stubs and place Python 2
stubs into `@python2` subdirectory for corresponding distribution. Note that
you don't need `@python2` in most cases, if your package supports Python 2,
just put the stubs at root of the distribution directory, and put
`python2 = True` in `METADATA.toml`.

Note: in its current implementation, typeshed cannot contain stubs for
multiple versions of the same third-party library. Prefer to generate
stubs for the latest version released on PyPI at the time of your
Expand Down