How to install type stubs for a third-party package like requests?

Use pip to install the corresponding stub package, e.g., 'pip install types-requests'. These packages are automatically released from typeshed and follow typing spec standards.

Typeshed vs inline type hints: which is better for library authors?

Inline type hints are preferred for libraries you control, as they provide runtime access and are part of the codebase. Typeshed is for external libraries without built-in hints, offering a community-driven fallback.

Why did my type checks break after updating stubs?

Breaking changes can occur in stub versions, as noted in the versioning strategies. This is because stubs are updated to reflect API changes, and mismatches with your code or runtime package can cause failures.

How to report a bug or missing type in typeshed?

File an issue on the typeshed GitHub issue tracker, not the original project. The README directs users here for annotation issues, and maintainers review community contributions.

Does typeshed support all Python versions?

Typeshed supports Python versions 3.10 to 3.14, as stated in the README. Stubs may not cover older versions extensively, so check compatibility if using legacy code.

What to do if a package isn't in typeshed?

You can write your own stub files or contribute to typeshed by following the CONTRIBUTING.md guidelines. Alternatively, rely on dynamic typing or use type: ignore comments in your code.

Open-Awesome

typeshed

NOASSERTIONPython

A collection of external type annotations (stubs) for the Python standard library and third-party packages.

GitHub

5.0k stars2.0k forks0 contributors

What is typeshed?

Typeshed is a collection of external type annotations (stub files) for Python's standard library and third-party packages. It provides the type definitions that static type checkers and IDEs use to perform type checking, inference, and autocompletion on Python code, solving the problem of missing or incomplete type hints in libraries.

Target Audience

Python developers using static type checkers (like mypy or pyright) or IDEs with type support, as well as library maintainers who want to provide or consume type annotations for their packages.

Value Proposition

Developers choose Typeshed because it offers a centralized, community-driven source of high-quality type stubs that are essential for accurate static analysis, reducing type-related errors and improving developer productivity across the Python ecosystem.

Overview

Collection of library stubs for Python, with static types

Use Cases

Best For

Adding type hints to untyped third-party Python libraries
Improving IDE autocompletion and inline type hints for standard library modules
Ensuring consistent type checking across teams using tools like mypy
Contributing type annotations to the Python typing ecosystem
Understanding the expected types of functions in external packages
Developing or maintaining static analysis tools for Python

Not Ideal For

Projects not using any static type checkers or IDEs with type support
Libraries with comprehensive, built-in type annotations that make external stubs redundant
Environments with strict dependency controls where adding stub packages is not feasible
Real-time applications where the overhead of type checking is undesirable

Pros & Cons

Pros

Comprehensive Standard Library Coverage

Provides full type annotations for Python's built-ins and standard library modules, enabling accurate static analysis without manual effort, as bundled with major type checkers.

Extensive Third-Party Support

Includes community-contributed stubs for popular external packages available via PyPI, such as types-requests, allowing type checking across a wide ecosystem.

Seamless Tool Integration

Designed to work effortlessly with static type checkers like mypy and pyright, improving developer workflow with autocompletion and error detection.

Version-Aware Stubbing

Stub packages follow the versioning of runtime packages, with clear strategies outlined in the README to manage compatibility, though with some risks.

Cons

Stub Update Lag

Stubs often lag behind the actual library releases, as admitted in the versioning section, leading to potential inaccuracies in type checking until updates are pushed.

Versioning Complexity and Breaking Changes

Any version bump can introduce breaking changes that disrupt type checking, requiring careful dependency management and pinning, which adds overhead.

Incomplete Package Coverage

Not all third-party packages have stubs, especially niche or proprietary ones, leaving gaps that developers must manually handle or ignore.

Frequently Asked Questions

Related Projects

ruff

An extremely fast Python linter and code formatter, written in Rust.

The uncompromising Python code formatter

Stars41,476

Forks2,758

Last commit2 days ago

mypy

Optional static typing for Python

Stars20,386

Forks3,169