typeshed
Generated by GPT-5-miniExpansion Funnel Raw 47 → Dedup 0 → NER 0 → Enqueued 0
typeshed Typeshed is a community-maintained collection of Python standard library and third-party library interface descriptions used to support static type checking and editor tooling. It provides stub files that describe APIs for runtime modules and packages so that tools can offer type information for libraries lacking inline annotations. The project is widely integrated into development tools and programming language infrastructure to bridge gaps between dynamic runtime behavior and static analysis.
Overview
The repository supplies .pyi stub files that capture function signatures, classes, constants, and documented behaviours for modules in the Python (programming language), and for popular packages such as NumPy, Requests (software), Pandas, Django (web framework), and Flask (web framework). Major consumers include static analyzers and language servers like mypy, pyright, Pyre (software), Jedi (software), and editors integrated with Visual Studio Code and PyCharm. Hosting and collaboration occur primarily on GitHub, with contributions from individual developers, open-source foundations, and corporate engineering teams from firms such as Microsoft, Google, and Instagram.
History
Origins trace to efforts by maintainers of mypy and early static typing adopters aiming to annotate the Python Standard Library without modifying upstream CPython runtime modules. The project grew through coordinated contributions from the broader Python Software Foundation community and related projects like PEP 484 discussion threads and PEP 561 packaging work. Over time, support for major scientific and web ecosystems expanded as projects including NumPy, Pandas, TensorFlow, and Django (web framework) influenced priorities and conventions. Key milestones include alignment with PEP 484 type hints, adoption by commercial tools from Microsoft and JetBrains, and periodic reorganization to accommodate evolving Python Enhancement Proposals.
Repository structure
The top-level layout separates stubs for the Python Standard Library and third-party packages. Directories mirror importable module names such as asyncio, socket (computer networking), http (protocol), and package trees like requests and sqlalchemy. Metadata and configuration files integrate with packaging standards referenced in PEP 561 and build tooling used by setuptools and pip. Tests, CI configuration leveraging GitHub Actions, and contributor guidelines are present alongside automated validation tools used by continuous integration systems at organizations like Microsoft and Google.
Stub file format and conventions
Stub files use the .pyi extension and adhere to syntax introduced by PEP 484 and subsequent PEPs that expanded typing capabilities, including PEP 585 and PEP 563. Conventions include use of names from typing such as List (abstract data type), Dict (abstract data type), Optional (type), and Union (type), as well as typing constructs introduced by PEP 604. Stubs aim to represent public APIs of packages like NumPy, where specialized typing protocols and generics are often necessary, and of frameworks like Django (web framework), which expose ORM classes and model descriptors. Documentation strings, overloads via typing.overload, and literal representations are used to model runtime behaviour while avoiding implementation details from CPython extensions and native bindings.
Maintenance and contribution workflow
Contribution follows standard open-source practices on GitHub: contributors open pull requests against the canonical repository, provide tests, and engage in code review by maintainers and community members. CI checks run static validation tools alongside test suites inspired by projects such as mypy and integration checks used by Pyright. Governance involves core maintainers and frequent contributors from companies including Microsoft, Google, Instagram, and institutions with large Python codebases. Contributions typically reference relevant Python Enhancement Proposals and issue threads to justify API representations and to ensure alignment with upstream libraries like NumPy or Requests (software).
Usage in type checking tools
Static type checkers such as mypy, Pyre (software), and pyright consume stubs to infer types for imports that lack inline annotations, improving diagnostics and autocompletion in editors such as Visual Studio Code and PyCharm. Language servers and tools like Pylance and Microsoft Python Language Server use the repository to supply richer IntelliSense. Continuous integration pipelines at organizations deploy these tools to enforce type quality across projects that depend on ecosystems like Django (web framework), Flask (web framework), NumPy, and Pandas.
Compatibility and limitations
Stubs cannot fully encode dynamic runtime behaviours from modules implemented as C extensions in CPython or from libraries that perform runtime metaprogramming common in Django (web framework) and SQLAlchemy. Compatibility is constrained by the expressive limits of PEP 484 and related typing enhancements; some projects resort to handwritten stubs, generated stubs via tools like stubgen from mypy, or gradual typing strategies. Differences between CPython and alternative interpreters such as PyPy can complicate assumptions in stubs, and versioned APIs across Python (programming language) releases require active maintenance.