VimPlug/typeshed
1
0
Fork 0
mirror of https://github.com/davidhalter/typeshed.git synced 2025-12-10 05:51:52 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Recommend scripts/create_baseline_stubs.py in CONTRIBUTING.md (#6906)

Browse Source
This commit is contained in:
Akuli
2022-01-13 16:11:20 +02:00
committed by GitHub
parent f42de016b8
commit 11642f866c
1 changed files with 23 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
CONTRIBUTING.md
View File

@@ -116,6 +116,8 @@ We accept stubs for third-party packages into typeshed as long as:
* the package supports any Python version supported by typeshed; and
* the package does not ship with its own stubs or type annotations.
The fastest way to generate new stubs is to use `scripts/create_baseline_stubs.py` (see below).
Stubs for third-party packages
go into `stubs`. Each subdirectory there represents a PyPI distribution, and
contains the following:
@@ -128,11 +130,6 @@ contains the following:
and also with Python 2 if `python2 = true` is set in `METADATA.toml` (see below).
* (Rarely) some docs specific to a given type stub package in `README` file.
The fastest way to generate new stubs is to use [stubgen](https://mypy.readthedocs.io/en/stable/stubgen.html),
a tool shipped with mypy. Please make sure to use the latest version.
The generated stubs usually need some trimming of imports. You also need
to run `black` and `isort` manually on the generated stubs (see below).
When a third party stub is added or
modified, an updated version of the corresponding distribution will be
automatically uploaded to PyPI within a few hours.
@@ -208,6 +205,27 @@ See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact
syntax of the stub files and [below](#stub-file-coding-style) for the
coding style used in typeshed.
### Auto-generating stub files
Typeshed includes `scripts/create_baseline_stubs.py`.
It generates stubs automatically using a tool called
[stubgen](https://mypy.readthedocs.io/en/latest/stubgen.html) that comes with mypy.
To get started, fork typeshed, clone your fork, and then
[create a virtualenv](#-or-create-a-local-development-environment).
You can then install the library with `pip` into the virtualenv and run the script,
replacing `libraryname` with the name of the library below:
```
(.venv3)$ pip install libraryname
(.venv3)$ python3 scripts/create_baseline_stubs.py libraryname
```
When the script has finished running, it will print instructions telling you what to do next.
If it has been a while since you set up the virtualenv, make sure you have
the latest mypy (`pip install -r requirements-tests.txt`) before running the script.
### Supported type system features
Since PEP 484 was accepted, there have been many other PEPs that added
@@ -341,15 +359,6 @@ class Foo:
def bar(x: str, y, *, z=...): ...
```
### Using stubgen
Mypy includes a tool called [stubgen](https://mypy.readthedocs.io/en/latest/stubgen.html)
that auto-generates stubs for Python and C modules using static analysis,
Sphinx docs, and runtime introspection. It can be used to get a starting
point for your stubs. Note that this generator is currently unable to
determine most argument and return types and omits them or uses ``Any`` in
their place. Fill out manually the types that you know.
## Stub file coding style
### Syntax example