py.typed

Overview

The file **`py.typed`** is a special marker file used in Python projects to indicate that the package contains [type hints](https://www.python.org/dev/peps/pep-0561/) compliant with [PEP 561](https://www.python.org/dev/peps/pep-0561/). Its presence signals to type checkers (like `mypy`, `pyright`, or IDEs with type inference) that the package includes inline type annotations or stub files, enabling enhanced static type checking for consumers of the package.

Unlike typical Python source code files, `py.typed` is usually empty and does not contain executable code, classes, or functions. Instead, it serves as a metadata marker recognized by tooling in the Python ecosystem.

Purpose and Functionality

• Purpose:
  To declare that the Python package is typed and supports static type checking.

• Functionality:
  When included in the root directory of a Python package (alongside __init__.py), py.typed tells type checkers that the package's .py files contain type annotations or that stub files (.pyi) are available. This lets tools provide accurate type checking and autocomplete for users of the package.

• File Content:
  Typically empty, or sometimes it may contain a single line with the string "partial" to indicate partial typing coverage as per PEP 561. However, the file content is optional.

Usage Example

Suppose you publish a package named `example_pkg` with type annotations:

example_pkg/
├── __init__.py
├── module.py        # contains type hints in its functions and classes
└── py.typed         # marker file (empty)

• When users install example_pkg, type checkers detect the py.typed file and enable type checking for this package automatically.

• Without py.typed, the package is treated as untyped, and type checkers won't validate or infer types from it.

Important Implementation Details

• Location:
  The py.typed file must reside in the root directory of the Python package directory (the same directory as __init__.py).

• File Content Variants:

  • Empty file: Indicates full typing coverage.

  • Contains "partial" (case insensitive): Indicates partial typing coverage, meaning some modules may not be fully typed.

• Packaging:
  The file must be included in the package distribution (e.g., in the source distribution and wheel) and declared in MANIFEST.in or package configuration files (setup.cfg, pyproject.toml) to ensure it is installed with the package.

• Compliance:
  This mechanism aligns with PEP 561 — Distributing and Packaging Type Information.

Interaction with Other Parts of the System

• Type Checkers and IDEs:
  Tools like mypy, pyright, PyCharm, and VSCode look for the py.typed marker to enable type checking against the package's code or stubs.

• Packaging Tools:
  Packaging tools like setuptools or flit must include the py.typed file inside the package when building distributions.

• Consumers of the Package:
  Developers importing the package get improved type inference and error detection thanks to the presence of py.typed.

Diagram

Since this file is a simple marker file without classes or functions, a flowchart illustrating its role in the type checking workflow is more appropriate than a class or component diagram.

flowchart TD
    A[Python Package]
    B[py.typed file present?]
    C[Type Checker (mypy, pyright)]
    D[Enable static type checking]
    E[Assume untyped package]
    
    A --> B
    B -- Yes --> C
    B -- No --> E
    C --> D

• If the py.typed file is detected in the package directory, type checkers enable static type checking for that package.

• Otherwise, the package is treated as untyped.

Summary

References

• PEP 561 – Distributing and Packaging Type Information

• Typing in Python

• Mypy Documentation on Typed Packages

This concludes the comprehensive documentation for the `py.typed` file.