py.typed

Overview

The `py.typed` file is a marker file used in Python projects to indicate that the package is **typed** and supports [PEP 561](https://www.python.org/dev/peps/pep-0561/) — the standard for distributing and consuming type information in Python packages. This file itself contains no code or configuration directives; its presence signals to type checkers (like `mypy`, `pyright`, or IDEs) that the package includes inline type annotations or [*.pyi](/projects/286/67331) stub files.

Purpose and Functionality

Purpose:
To declare that the Python package or module containing this file provides type information.
Functionality:
The file acts as a marker without executable content. When a type checker encounters a directory containing py.typed, it treats the package as typed, enabling static type checking on code that imports it.

Important Implementation Details

The file must be included in the package distribution (e.g., via MANIFEST.in or setup.cfg configuration) for the typing indication to be effective.
It should be placed at the root of the package directory (the same place as the __init__.py file).
The file can be either empty or contain the text partial to indicate a partially typed package (in which not all parts of the package are fully typed). An empty file means the package is fully typed.
Example contents:
- Fully typed package:
```
(empty file)
```
- Partially typed package:
```
partial
```

Interaction with Other Parts of the System

Type Checkers:
Tools like mypy and pyright look for py.typed to determine if they should apply type checking on a package.
Package Distribution:
When publishing the package (to PyPI or other indexes), including py.typed ensures users of the package benefit from type hints.
Developers and IDEs:
IDEs that support Python typing will recognize typed packages and provide enhanced auto-completion, linting, and error detection.

Usage Example

Suppose you have a package structure:

my_package/
├── __init__.py
├── module.py
└── py.typed

The presence of py.typed informs type checkers that my_package contains type annotations.
If you omit py.typed, type checkers will treat my_package as untyped, even if it contains type hints.

Summary

Aspect	Description
File type	Marker file (no executable code)
Location	Root of the typed Python package directory
Content	Empty or contains `partial`
Purpose	Signal type checker to consider package typed
Required for	Enabling PEP 561 typing support
Effect	Enables static type checking on package usage

Visual Diagram

Since `py.typed` is a marker file without classes or functions, the most appropriate diagram is a flowchart showing its role within the package typing ecosystem:

flowchart TD
    A[Python Package Directory]
    B[py.typed file]
    C[Type Checkers (mypy, pyright, etc.)]
    D[IDE / Editor]
    E[Package Consumers]

    A --> B
    B --> C
    B --> D
    C --> E
    D --> E

    style B fill:#f9f,stroke:#333,stroke-width:2px
    click B "https://www.python.org/dev/peps/pep-0561/" "PEP 561: Distributing and Packaging Type Information"

Additional Notes

The py.typed file is part of best practices for modern Python packaging to support static typing.
It helps improve code quality and developer experience by enabling type-aware tooling.
Its simplicity belies its critical role in Python’s gradual typing ecosystem.

If you need documentation for a Python source file or a module, please provide the code content for detailed analysis and documentation.