PEP 561

PEP 561
Title	PEP 561
Status	Final
Author	Łukasz Langa
Created	2018-02-12
Python versions	3.x

PEP 561

PEP 561 formalizes a packaging and distribution approach to ship type information for third-party libraries. It defines metadata conventions, distribution artifacts, and compatibility constraints to enable static type checkers and tooling to consume type information distributed with packages. The proposal interfaces with packaging ecosystems and toolchains to improve interoperability across projects and environments.

Background

Type checking in Python evolved through contributions from figures and projects such as Guido van Rossum, Brett Cannon, Mypy, PyPI, PEP 484, and Python Software Foundation. Tooling like PyCharm, Visual Studio Code, Jedi (software), and Sublime Text integrated static analysis features driven by community efforts around Python Enhancement Proposals and standards bodies. Distribution practices shaped by setuptools, pip, wheel (package format), and distutils influenced how metadata could be attached to packages to convey additional information.

Purpose and Scope

The specification aims to standardize how type information accompanies binary and source distributions created by setuptools, wheel (package format), and pip. It specifies interactions relevant to static analyzers such as Mypy, Pyright, and Pyre (software), and to IDEs like PyCharm and Visual Studio Code. The scope covers packaging metadata, discovery rules, and compatibility with package indexes including PyPI and alternate registries used by organizations like Anaconda, Inc..

Specification

The PEP prescribes a clear file layout and metadata markers for type stubs and inline annotations. It defines the use of a marker file and package data fields compatible with standards developed in concert with PEP 440, PEP 517, and PEP 518. The spec details expectations for stub packages produced by projects such as typeshed, and for inline-annotated libraries written by maintainers of projects like Requests (software), NumPy, Pandas (software), and Django (web framework). It clarifies discovery precedence between distributed stubs and during-installation tools like pip when resolving dependencies declared in setup.py or pyproject.toml.

Packaging and Distribution

Implementers pack type information either inside a distribution or as a separate "type stub" distribution, similar to practices by organizations such as Microsoft, Google, and Instagram (company) when contributing stubs to typeshed. The PEP aligns with distribution formats like wheel (package format) and integrates metadata keys that work with index servers including PyPI and mirrors run by entities like GitHub and GitLab. Packaging tools including setuptools, flit, and poetry adopted conventions to produce compliant artifacts that annotations-aware tools can consume.

Adoption and Tooling

Adoption involved collaboration among maintainers and tooling projects: core developers from Mypy, contributors from typeshed, IDE teams at JetBrains, and language service authors at Microsoft. Continuous integration platforms such as Travis CI, GitHub Actions, and CircleCI incorporated checks for the packaging markers. Major libraries including NumPy, Pandas (software), Django (web framework), Flask (web framework), Requests (software), and SQLAlchemy integrated distributed type information following the PEP.

Examples and Usage

Common usage patterns include embedding inline annotations in packages like NumPy and publishing separate stub packages analogous to contributions in typeshed. A package author updates setup.cfg or pyproject.toml to include metadata indicating shipped types, and CI runs verify artifact contents before twine uploads to PyPI. Consumers running tools such as Mypy, Pyright, Pyre (software), PyCharm, or Visual Studio Code pick up distributed type data per the PEP's discovery rules.

Compatibility and Limitations

The approach balances backward compatibility with older packaging tools like distutils while leveraging modern helpers such as PEP 517-based build backends. Limitations arise when packages use conditional imports or C extensions as in projects from organizations like Numba or Cython-based modules, where stub generation can be nontrivial. Ecosystem fragmentation—across package indexes, build backends, and language servers maintained by Microsoft, JetBrains, and other vendors—affects uniform adoption, and some legacy distributions still require separate maintenance or community-provided stubs in typeshed.

Category:Python PEPs