• Stars
    star
    4,316
  • Rank 9,981 (Top 0.2 %)
  • Language
    Python
  • License
    Other
  • Created almost 10 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Collection of library stubs for Python, with static types

typeshed

Tests Chat at https://gitter.im/python/typing Pull Requests Welcome

About

Typeshed contains external type annotations for the Python standard library and Python builtins, as well as third party packages as contributed by people 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 for contributors can be found in CONTRIBUTING.md. Please read it before submitting pull requests; do not report issues with annotations to the project the stubs are for, but instead report them here to typeshed.

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

Typeshed supports Python versions 3.8 and up.

Using

If you're just using a type checker (mypy, pyright, pytype, PyCharm, ...), as opposed to developing it, you don't need to interact with the typeshed repo at all: 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 can be installed from PyPI. For example, if you are using html5lib and requests, you can install the type stubs using

$ pip install types-html5lib types-requests

These PyPI packages follow PEP 561 and are automatically released (up to once a day) by typeshed internal machinery.

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

Package versioning for third-party stubs

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 the version of the runtime package being stubbed. For example, if the types-foo package has version 1.2.0.20240309, this guarantees that the types-foo package contains stubs targeted against foo==1.2.* and tested against the latest version of foo matching that specifier. In this example, the final element of the version number (20240309) indicates that the stub package was pushed on March 9, 2024.

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

There are several strategies available for specifying the version of a stubs package 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 use requests>=2.30.0,<2.32, you can use types-requests>=2.30.0,<2.32. This ensures that the stubs are compatible with the package you are using, but it carries a small risk of breaking type checking due to changes in the stubs.

    Another risk of this strategy is that stubs often lag behind the package being stubbed. You might want to force the package being stubbed to a certain minimum version because it fixes a critical bug, but if correspondingly updated stubs have not been released, your type checking 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 use types-requests==2.31.0.1, you can have confidence that upgrading dependencies will not break type checking. However, you will miss out on improvements in the stubs that could potentially improve type checking until you update the pin. This strategy also has the risk that the stubs 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 from you when it comes to updating version pins, and has the advantage that you will automatically benefit from improved stubs whenever a new version of the stubs package is released. However, it carries the risk that the stubs become incompatible with the package being stubbed.

    For example, if a new major version of the package is released, there's a chance the stubs might be updated to reflect the new version of the runtime package 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) when a problem arises that can't easily be fixed.

The _typeshed package

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

Discussion

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

Our main forum for discussion is the project's GitHub issue tracker. This is the right place to start a discussion of any of the above or most any other topic concerning the project.

If you have general questions about typing with Python, or you need a review of your type annotations or stubs outside of typeshed, head over to our discussion forum. For less formal discussion, try the typing chat room on gitter.im. Some typeshed maintainers are almost always present; feel free to find us there and we're happy to chat. Substantive technical discussion will be directed to the issue tracker.

More Repositories

1

cpython

The Python programming language
Python
55,867
star
2

mypy

Optional static typing for Python
Python
18,263
star
3

peps

Python Enhancement Proposals
reStructuredText
4,337
star
4

devguide

The Python developer's guide
Python
1,841
star
5

typing

Python static typing home. Hosts the documentation and a user help forum.
Python
1,587
star
6

pythondotorg

Source code for python.org
Python
1,414
star
7

asyncio

asyncio historical repository
1,015
star
8

pyperformance

Python Performance Benchmark Suite
Python
847
star
9

python-docs-zh-cn

zh_CN translation of the Python documentation
431
star
10

typing_extensions

Backported and experimental type hints for Python
Python
418
star
11

python-docs-fr

Mirroir en lecture seule de https://git.afpy.org/AFPy/python-docs-fr
355
star
12

python-docs-es

Spanish translation of the Python documentation.
Python
319
star
13

python-docs-zh-tw

Traditional Chinese (zh-tw) translation of the Python Documentation
Python
246
star
14

typed_ast

Modified fork of CPython's ast module that parses `# type:` comments
C
227
star
15

raspberryio

Source code for raspberry.io
Python
222
star
16

steering-council

Communications from the Steering Council
Makefile
138
star
17

mypy_extensions

Extensions for mypy
Python
134
star
18

planet

Configuration for Python planets (e.g. http://planetpython.org)
Python
132
star
19

python-docs-pt-br

Brazilian Portuguese translation of the Python Documentation
Makefile
115
star
20

bedevere

A bot to help identify missing information for CPython pull requests
Python
113
star
21

python-docs-tr

Turkish Translation of the Python Documentation
Python
112
star
22

miss-islington

๐Ÿ๐Ÿ’โ›๐Ÿค– - A bot for backporting and merging CPython pull requests
Python
104
star
23

psf-salt

PSF infrastructure configuration
SaltStack
104
star
24

importlib_metadata

Backport of the importlib.metadata module
Python
100
star
25

pycon-code-of-conduct

pycon code of conduct
97
star
26

core-workflow

Issue tracker for CPython's workflow
Python
87
star
27

the-knights-who-say-ni

CLA enforcement bot for Python organization projects
Python
81
star
28

tzdata

Python package wrapping the IANA time zone database
Python
76
star
29

python-docs-theme

Sphinx theme for Python documentation
CSS
73
star
30

python-docs-ko

Korean translation of the Python documentation
63
star
31

python-docs-ja

Shell
61
star
32

docsbuild-scripts

scripts for building documentation on docs.python.org
Python
61
star
33

python-docs-id

Terjemahan Bahasa Indonesia untuk Dokumentasi Python
58
star
34

pythoncapi-compat

The pythoncapi-compat project can be used to write a C extension supporting a wide range of Python versions with a single code base.
Python
53
star
35

importlib_resources

Backport of the importlib.resources module
Python
52
star
36

cherry-picker

๐Ÿ๐Ÿ’โ› Utility script for backporting/cherry-picking CPython changes from master into one of the maintenance branches.
Python
48
star
37

community-starter-kit

Collection of resources for Python community organizers
Python
46
star
38

python-docs-pl

Polskie tล‚umaczenie dokumentacji Pythona
Python
46
star
39

getpython3.com

getpython3.com page and resources.
CSS
44
star
40

psf-chef

Chef configuration and cookbooks for the Python Software Foundation
Ruby
44
star
41

typing-council

Decisions by the Python Typing Council
42
star
42

docs-community

Community management for documentation contributors and the Docs Workgroup
Makefile
41
star
43

pythonineducation.org

The pythonineducation.org website
HTML
29
star
44

release-tools

Scripts for making (C)Python releases
Python
28
star
45

buildmaster-config

Configuration for buildbot.python.org
Python
27
star
46

blurb_it

`blurb add` over the internet
Python
26
star
47

cpython-bin-deps

Binaries that the cpython build process depends on
22
star
48

exceptiongroups

An early draft of a PEP around Exception Groups in Python
22
star
49

cpython-source-deps

Source for packages that the cpython build process depends on
22
star
50

python-docs-uk

Ukrainian translation of the Python Documentation
Makefile
21
star
51

discord-bot

Discord Bot for Core Devs Discord server
Python
20
star
52

psf-docs

PSF Docs
Python
18
star
53

historic-python-materials

Contains some old pages from python.org
Python
18
star
54

consul-operator

A kubernetes operator for consul
Go
17
star
55

core-sprint

Repo for Virtual Core Dev Sprint 2020
Python
16
star
56

speed.python.org

HTML
14
star
57

devinabox

Documentation and tools to help host a sprint on Python core development
Python
14
star
58

docker-bpo

Docker image for bugs.python.org
Python
14
star
59

pythontestdotnet

source of pythontest.net (resources used for Python test suite)
HTML
12
star
60

.github

Organization-wide GitHub settings
11
star
61

bugs.python.org

Meta-issue tracker for bugs.python.org
11
star
62

hugs.python.org

10
star
63

psf-infra-meta

Meta-repository for PSF backed or managed systems. Created mainly for the issue tracker :)
10
star
64

psf-community-resources

Short guides to PSF-related resources
10
star
65

python-docs-it

Italian translation of the Python documentation.
10
star
66

python-dev-survey

Place for gathering feedback from the public on the Python Developers Survey
8
star
67

bpo-builder

bugs.python.org builder image & other deployment artifacts
Python
7
star
68

language-summit

Resources for the annual Python Language Summit
7
star
69

python-docs-hu

Hungarian Translation of the Python Documentation
7
star
70

psfoutreach

PSF Outreach website
Shell
6
star
71

tlsproxy

Python
6
star
72

psf-packages

HTML
5
star
73

redistributor-guide

Guidance & recommendations for anyone publishing their own binary builds of CPython
4
star
74

overload-sig

Discussion about discussion overload, see https://mail.python.org/mm3/mailman3/lists/[email protected]/
4
star
75

issues-test-cpython

Test repository for the bpo migration
3
star
76

python-docs-bn-in

3
star
77

cpython-devcontainers

Repository for devcontainers of CPython
Dockerfile
2
star
78

pootle-python-org-backup

Python
2
star
79

issues-test-demo-20220218

Test repository for the bpo migration
1
star
80

issues-test-demo-20220402

Test repository for the bpo migration
1
star