+
+ | Linux / macOS / WSL |
+
+
+ On Linux and macOS, you will be able to run the full test suite on Python
+ 3.9-3.12.
+ To install the necessary requirements, run the following commands from a
+ terminal window:
+
+ ```bash
+ $ python3 -m venv .venv
+ $ source .venv/bin/activate
+ (.venv)$ pip install -U pip
+ (.venv)$ pip install -r requirements-tests.txt
+ ```
+
+ |
+
+|
+
+ | Windows |
+
+
+ Run the following commands from a Windows terminal to install all requirements:
+
+ ```powershell
+ > python -m venv .venv
+ > .venv\Scripts\activate
+ (.venv) > pip install -U pip
+ (.venv) > pip install -r requirements-tests.txt
+ ```
+
+ To be able to run pytype tests, you'll also need to install it manually
as it's currently excluded from the requirements file:
-```powershell
-(.venv) > pip install -U pytype
-```
+ ```powershell
+ (.venv) > pip install -U pytype
+ ```
-## Code formatting
+ |
+
+|
+
+ | Using uv |
+
-The code is formatted using [`Black`](https://github.com/psf/black).
-Various other autofixes and lint rules are
-also performed by [`Ruff`](https://github.com/astral-sh/ruff) and
-[`Flake8`](https://github.com/pycqa/flake8),
-with plugins [`flake8-pyi`](https://github.com/pycqa/flake8-pyi),
-and [`flake8-noqa`](https://github.com/plinss/flake8-noqa).
+ If you already have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, you can simply replace the commands above with:
-The repository is equipped with a [pre-commit.ci](https://pre-commit.ci/)
-configuration file. This means that you don't *need* to do anything yourself to
-run the code formatters or linters. When you push a commit, a bot will run
-those for you right away and add any autofixes to your PR. Anything
-that can't be autofixed will show up as a CI failure, hopefully with an error
-message that will make it clear what's gone wrong.
+ ```shell
+ uv venv
+ uv pip install -r requirements-tests.txt
+ ```
-That being said, if you *want* to run the formatters and linters locally
-when you commit, you're free to do so. To use the same configuration as we use
-in CI, we recommend doing this via pre-commit:
+ ```shell
+ uv pip install -U pytype
+ ```
-```bash
-(.venv)$ pre-commit run --all-files
-```
+ |
+
+
## Where to make changes
@@ -223,6 +229,12 @@ This has the following keys:
If not specified, stubtest is run only on `linux`.
Only add extra OSes to the test
if there are platform-specific branches in a stubs package.
+* `mypy_plugins` (default: `[]`): A list of Python modules to use as mypy plugins
+when running stubtest. For example: `mypy_plugins = ["mypy_django_plugin.main"]`
+* `mypy_plugins_config` (default: `{}`): A dictionary mapping plugin names to their
+configuration dictionaries for use by mypy plugins. For example:
+`mypy_plugins_config = {"django-stubs" = {"django_settings_module" = "@tests.django_settings"}}`
+
`*_dependencies` are usually packages needed to `pip install` the implementation
distribution.
@@ -231,7 +243,7 @@ The format of all `METADATA.toml` files can be checked by running
`python3 ./tests/check_typeshed_structure.py`.
-## Preparing Changes
+## Making Changes
### Before you begin
@@ -246,6 +258,27 @@ Each Python module is represented by a .pyi "stub file". This is a syntactically
Typeshed follows the standard type system guidelines for [stub content](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#stub-content) and [coding style](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#style-guide).
+The code is formatted using [`Black`](https://github.com/psf/black).
+Various other autofixes and lint rules are
+also performed by [`Ruff`](https://github.com/astral-sh/ruff) and
+[`Flake8`](https://github.com/pycqa/flake8),
+with plugin [`flake8-pyi`](https://github.com/pycqa/flake8-pyi).
+
+The repository is equipped with a [pre-commit.ci](https://pre-commit.ci/)
+configuration file. This means that you don't *need* to do anything yourself to
+run the code formatters or linters. When you push a commit, a bot will run
+those for you right away and add any autofixes to your PR. Anything
+that can't be autofixed will show up as a CI failure, hopefully with an error
+message that will make it clear what's gone wrong.
+
+That being said, if you *want* to run the formatters and linters locally
+when you commit, you're free to do so. To use the same configuration as we use
+in CI, we recommend doing this via pre-commit:
+
+```bash
+(.venv)$ pre-commit run --all-files
+```
+
### What to include
Stubs should include the complete interface (classes, functions,
@@ -433,33 +466,6 @@ steps:
If feeling kindly, please update [mypy](https://github.com/python/mypy/blob/master/mypy/stubinfo.py)
for any stub obsoletions or removals.
-## Maintainer guidelines
-
-The process for preparing and submitting changes also applies to
-maintainers. This ensures high quality contributions and keeps
-everybody on the same page. Avoid direct pushes to the repository.
-
-When reviewing pull requests, follow these guidelines:
-
-* Typing is hard. Try to be helpful and explain issues with the PR,
- especially to new contributors.
-* When reviewing auto-generated stubs, just scan for red flags and obvious
- errors. Leave possible manual improvements for separate PRs.
-* When reviewing large, hand-crafted PRs, you only need to look for red flags
- and general issues, and do a few spot checks.
-* Review smaller, hand-crafted PRs thoroughly.
-
-When merging pull requests, follow these guidelines:
-
-* Always wait for tests to pass before merging PRs.
-* Use "[Squash and merge](https://github.com/blog/2141-squash-your-commits)" to merge PRs.
-* Make sure the commit message is meaningful. For example, remove irrelevant
- intermediate commit messages.
-* The commit message for third-party stubs is used to generate the changelog.
- It should be valid Markdown, be comprehensive, read like a changelog entry,
- and assume that the reader has no access to the diff.
-* Delete branches for merged PRs (by maintainers pushing to the main repo).
-
### Marking PRs as "deferred"
We sometimes use the ["status: deferred" label](https://github.com/python/typeshed/labels/status%3A%20deferred)
@@ -471,25 +477,9 @@ external factor. Blockers can include:
- A dependency on a typing PEP that is still under consideration.
- A pending change in a related project, such as stub-uploader.
-PRs should only be marked as "deferred" if there is a clear path towards getting
-the blocking issue resolved within a reasonable time frame. If a PR depends on
-a more amorphous change, such as a type system change that has not yet reached
-the PEP stage, it should instead be closed.
-
-Maintainers who add the "deferred" label should state clearly what exactly the
-blocker is, usually with a link to an open issue in another project.
-
### Closing stale PRs
To keep the number of open PRs manageable, we may close PRs when they have been
open for too long. Specifically, we close open PRs that either have failures in CI,
serious merge conflicts or unaddressed feedback, and that have not seen any
activity in three months.
-
-We want to maintain a welcoming atmosphere for contributors, so use a friendly
-message when closing the PR. Example message:
-
- Thanks for contributing! I'm closing this PR for now, because it still
-