Typeshed

Stubs for stdlib

Mypy ships with stubs for stdlib modules copied from the typeshed project under mypy/typeshed. These are absolutely essential for basic operation, as the stubs also include definitions of built-in types such as int and list and stubs for the typing module, among other things.

Stubs for third-party libraries

Typeshed also includes stubs for many third-party libraries. These are not shipped with mypy and must be explicitly installed by users (e.g. pip install types-requests). This allows updating library stubs without having to update mypy, and it also enables pinning the versions of library stubs. This makes it easier to update to more recent mypy versions.

In mypy versions earlier than 0.900 third-party library stubs were shipped with mypy.

Note that many libraries include type annotations or bundle stubs (PEP 561 explains how this works). This is the preferred way of providing type information for third-party libraries.

Updating stdlib stubs

Each mypy feature release includes updated versions of typeshed stubs. Use the misc/sync-typeshed.py script to create a commit that updates the vendored stdlib in the mypy repository.

When updating stubs, pay close attention to mypy_primer results that are posted as comments to mypy PRs, as typeshed changes frequently causes regressions.

Sometimes a regression is caused by incorrect types in typeshed. These should be fixed by with a typeshed PR. After the typeshed PR has been merged, re-run the sync-typeshed.py script.

Sometimes a typeshed change triggers a mypy bug. For example, particularly complex types can cause problems, or new types that use recently implemented type system features could expose a gap in the implementation. In these cases we should first fix the issue in mypy before merging the typeshed sync commit.

If a regression is hard to fix, we can occasionally revert an individual typeshed commit when syncing stubs. The regression should be fixed soon, however, since managing reverted commits across multiple mypy releases will complicate the release process.

We also sometimes cherry-pick individual typeshed commits to mypy to unblock a mypy release or work around a major issue. Normally, however, we prefer to sync all stdlib stubs at the same time to a particular typeshed commit.

Stubs used in test cases

Most test cases don't use typeshed to speed up tests. Instead, they use much smaller test fixtures from test-data/unit/lib-stub (minimal stubs used by default) and test-data/unit/fixtures (individual test cases can opt in to more general stubs from here). For more information, refer to our documentation on tests.

If a test case requires full typeshed stubs, you can add a test case to test-data/unit/pythoneval.test. These test cases are very slow to run and should be avoided unless absolutely necessary.