From 11642f866cb2ec79d6119024f88639470976204f Mon Sep 17 00:00:00 2001 From: Akuli Date: Thu, 13 Jan 2022 16:11:20 +0200 Subject: [PATCH] Recommend scripts/create_baseline_stubs.py in CONTRIBUTING.md (#6906) --- CONTRIBUTING.md | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 15492cf60..43739e129 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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