Repository files navigation

Typeshed contains external type annotations for the Python standard libraryand Python builtins, as well as third party packages as contributed bypeople external to those projects.

This data can e.g. be used for static analysis, type checking, type inference,and autocompletion.

For information on how to use typeshed, read below. Information forcontributors can be found inCONTRIBUTING.md.Please readit before submitting pull requests; do not report issues with annotations tothe project the stubs are for, but instead report them here to typeshed.

Further documentation on stub files, typeshed, and Python's typing system ingeneral, can also be found athttps://typing.readthedocs.io/en/latest/.

Typeshed supports Python versions 3.9 to 3.13.

If you're just using a type checker (mypy,pyright,pytype, PyCharm, ...), as opposed todeveloping it, you don't need to interact with the typeshed repo atall: a copy of standard library part of typeshed is bundled with type checkers.And type stubs for third party packages and modules you are using canbe installed from PyPI. For example, if you are usinghtml5lib andrequests,you can install the type stubs using

$ pip install types-html5lib types-requests

These PyPI packages followPEP 561and are automatically released (up to once a day) bytypeshed internal machinery.

Type checkers should be able to use these stub packages when installed. For moredetails, see the documentation for your type checker.

Version numbers of third-party stub packages consist of at least four parts.All parts of the stub version, except for the last part, correspond to theversion of the runtime package being stubbed. For example, if thetypes-foopackage has version1.2.0.20240309, this guarantees that thetypes-foo packagecontains stubs targeted againstfoo==1.2.* and tested against the latestversion offoo matching that specifier. In this example, the final elementof the version number (20240309) indicates that the stub package was pushed onMarch 9, 2024.

At typeshed, we try to keep breaking changes to a minimum. However, due to thenature of stubs, any version bump can introduce changes that might make yourcode fail to type check.

There are several strategies available for specifying the version of a stubspackage you're using, each with its own tradeoffs:

1. Use the same bounds that you use for the package being stubbed. For example,if you userequests>=2.30.0,<2.32, you can usetypes-requests>=2.30.0,<2.32. This ensures that the stubs are compatiblewith the package you are using, but it carries a small risk of breakingtype checking due to changes in the stubs.

   Another risk of this strategy is that stubs often lag behindthe package being stubbed. You might want to force the package being stubbedto a certain minimum version because it fixes a critical bug, but ifcorrespondingly updated stubs have not been released, your typechecking results may not be fully accurate.

2. Pin the stubs to a known good version and update the pin from time to time(either manually, or using a tool such as dependabot or renovate).

   For example, if you usetypes-requests==2.31.0.1, you can have confidencethat upgrading dependencies will not break type checking. However, you willmiss out on improvements in the stubs that could potentially improve typechecking until you update the pin. This strategy also has the risk that thestubs you are using might become incompatible with the package being stubbed.

3. Don't pin the stubs. This is the option that demands the least work fromyou when it comes to updating version pins, and has the advantage that youwill automatically benefit from improved stubs whenever a new version of thestubs package is released. However, it carries the risk that the stubsbecome incompatible with the package being stubbed.

   For example, if a new major version of the package is released, there's achance the stubs might be updated to reflect the new version of the runtimepackage before you update the package being stubbed.

You can also switch between the different strategies as needed. For example,you could default to strategy (1), but fall back to strategy (2) whena problem arises that can't easily be fixed.

typeshed includes a package_typeshed as part of the standard library.This package and its submodules contain utility types, but are notavailable at runtime. For more information about how to use this package,see thestdlib/_typeshed directory.

If you've run into behavior in the type checker that suggests the typestubs for a given library are incorrect or incomplete,we want to hear from you!

Our main forum for discussion is the project'sGitHub issuetracker. This is the rightplace to start a discussion of any of the above or most any othertopic concerning the project.

If you have general questions about typing with Python, or you needa review of your type annotations or stubs outside of typeshed, head over toour discussion forum.For less formal discussion, try the typing chat room ongitter.im. Some typeshed maintainersare almost always present; feel free to find us there and we're happyto chat. Substantive technical discussion will be directed to theissue tracker.