Contents

• Abstract
• Rationale
• Definition of Terms
• Specification
  • Packaging Type Information
    • Stub-only Packages
  • Type Checker Module Resolution Order
  • Partial Stub Packages
• Implementation
• Acknowledgements
• Version History
• References
• Copyright

Abstract

PEP 484 introduced type hinting to Python, with goals of making typing gradual and easy to adopt. Currently, typing information must be distributed manually. This PEP provides a standardized means to leverage existing tooling to package and distribute type information with minimal work and an ordering for type checkers to resolve modules and collect this information for type checking.

Rationale

Currently, package authors wish to distribute code that has inline type information. Additionally, maintainers would like to distribute stub files to keep Python 2 compatibility while using newer annotation syntax. However, there is no standard method to distribute packages with type information. Also, if one wished to ship stub files privately the only method available would be via setting MYPYPATH or the equivalent to manually point to stubs. If the package can be released publicly, it can be added to typeshed 1. However, this does not scale and becomes a burden on the maintainers of typeshed. In addition, it ties bug fixes in stubs to releases of the tool using typeshed.

PEP 484 has a brief section on distributing typing information. In this section 2 the PEP recommends using shared/typehints/pythonX.Y/ for shipping stub files. However, manually adding a path to stub files for each third party library does not scale. The simplest approach people have taken is to add site-packages to their MYPYPATH, but this causes type checkers to fail on packages that are highly dynamic (e.g. sqlalchemy and Django).

Definition of Terms

The definition of “MAY”, “MUST”, and “SHOULD”, and “SHOULD NOT” are to be interpreted as described in RFC 2119.

“inline” - the types are part of the runtime code using PEP 526 and PEP 3107 syntax (the filename ends in .py).

“stubs” - files containing only type information, empty of runtime code (the filename ends in .pyi).

“Distributions” are the packaged files which are used to publish and distribute a release. 3

“Module” a file containing Python runtime code or stubbed type information.

“Package” a directory or directories that namespace Python modules. (Note the distinction between packages and distributions. While most distributions are named after the one package they install, some distributions install multiple packages.)

Specification

There are several motivations and methods of supporting typing in a package. This PEP recognizes three types of packages that users of typing wish to create:

1. The package maintainer would like to add type information inline.
2. The package maintainer would like to add type information via stubs.
3. A third party or package maintainer would like to share stub files for a package, but the maintainer does not want to include them in the source of the package.

This PEP aims to support all three scenarios and make them simple to add to packaging and deployment.

The two major parts of this specification are the packaging specifications and the resolution order for resolving module type information. The type checking spec is meant to replace the shared/typehints/pythonX.Y/ spec of PEP 484 2.

New third party stub libraries SHOULD distribute stubs via the third party packaging methods proposed in this PEP in place of being added to typeshed. Typeshed will remain in use, but if maintainers are found, third party stubs in typeshed MAY be split into their own package.

setup(
    ...,
    package_data = {
        'foopkg': ['py.typed'],
    },
    ...,
    )

shapes-stubs
└── polygons
    └── pentagon
        └── __init__.pyi

shapes-stubs
└── polygons
    └── hexagon
        └── __init__.pyi

Implementation

The proposed scheme of indicating support for typing is completely backwards compatible, and requires no modification to package tooling. A sample package with inline types is available [typed_package], as well as a [stub_package]. A sample package checker [pkg_checker] which reads the metadata of installed packages and reports on their status as either not typed, inline typed, or a stub package.

The mypy type checker has an implementation of PEP 561 searching which can be read about in the mypy docs 4.

[numpy-stubs] is an example of a real stub-only package for the numpy distribution.

Acknowledgements

This PEP would not have been possible without the ideas, feedback, and support of Ivan Levkivskyi, Jelle Zijlstra, Nick Coghlan, Daniel F Moisset, Andrey Vlasovskikh, Nathaniel Smith, and Guido van Rossum.

Version History

• 2021-09-20

  • Clarify expectations and typechecker behavior for stub-only namespace packages
  • Clarify handling of single-file modules within namespace packages.

• 2018-07-09

  • Add links to sample stub-only packages

• 2018-06-19

  • Partial stub packages can look at typeshed as well as runtime packages

• 2018-05-15

  • Add partial stub package spec.

• 2018-04-09

  • Add reference to mypy implementation
  • Clarify stub package priority.

• 2018-02-02

  • Change stub-only package suffix to be -stubs not _stubs.
  • Note that py.typed is not needed for stub-only packages.
  • Add note about pip and upgrading stub packages.

• 2017-11-12

  • Rewritten to use existing tooling only
  • No need to indicate kind of type information in metadata
  • Name of marker file changed from .typeinfo to py.typed

• 2017-11-10

  • Specification re-written to use package metadata instead of distribution metadata.
  • Removed stub-only packages and merged into third party packages spec.
  • Removed suggestion for typecheckers to consider checking runtime versions
  • Implementations updated to reflect PEP changes.

• 2017-10-26

  • Added implementation references.
  • Added acknowledgements and version history.

• 2017-10-06

  • Rewritten to use .distinfo/METADATA over a distutils specific command.
  • Clarify versioning of third party stub packages.

• 2017-09-11

  • Added information about current solutions and typeshed.
  • Clarify rationale.

References

1

Typeshed (https://github.com/python/typeshed)

2 (1, 2)

PEP 484, Storing and Distributing Stub Files (https://www.python.org/dev/peps/pep-0484/#storing-and-distributing-stub-files)

3

PEP 426 definitions (https://www.python.org/dev/peps/pep-0426/)

4

Example implementation in a type checker (https://mypy.readthedocs.io/en/latest/installed_packages.html)

stub_package

A stub-only package (https://github.com/ethanhs/stub-package)

typed_package

Sample typed package (https://github.com/ethanhs/sample-typed-package)

numpy-stubs

Stubs for numpy (https://github.com/numpy/numpy-stubs)

pkg_checker

Sample package checker (https://github.com/ethanhs/check_typedpkg)

Copyright

This document has been placed in the public domain.