py.typed

Overview

The `py.typed` file is a marker file used in Python packages to indicate that the package includes inline type hints or distributed type stub files (`.pyi`). Its primary purpose is to signal to type checkers (such as `mypy`, `pyright`, or PyCharm’s built-in type checker) that the package supports static type checking.

This file itself contains no executable code or definitions. Instead, it serves as a metadata file that enables the Python typing ecosystem to recognize that the package is **PEP 561 compliant** (i.e., it provides type information).

Purpose and Functionality

• Purpose:
  To mark a Python package as type hint compliant by adhering to PEP 561, allowing static type checkers to find and use type information bundled with the package.

• Functionality:
  When a package directory contains a py.typed file, type checkers look inside the package for inline type annotations or type stub files. This improves developer experience by enabling better autocompletion, type safety, and static analysis tools integration.

• The file is typically empty or contains minimal content (like the string "partial" if the package partially supports typing), but most commonly it is just an empty file.

Implementation Details

• The presence of this file in a package directory is the only requirement to mark the package as typed.

• It should be included in the package's distribution, specifically inside the package directory (e.g., orjson/py.typed).

• It is usually an empty file with no content, but optionally it can contain the line partial to indicate partial type hint coverage.

• It does not define any classes, functions, or variables.

• It has no runtime effect and does not interact with the package logic or runtime behavior.

• Tools like setuptools or poetry need configuration to ensure this file is included in the package distribution (e.g., via include_package_data or MANIFEST.in).

Interaction with the System / Application

• The py.typed file is part of the Python API package distribution, for instance in the orjson package.

• It enables type checkers to leverage the rich typing information provided by the package, improving static analysis when using the package in Python projects.

• This facilitates better integration of the orjson package's Python API (which exposes Rust-accelerated JSON serialization/deserialization) into Python developer workflows.

• It complements the package’s .pyi stub files or inline annotations, making the package fully type-aware.

• The file affects development tools only and does not affect runtime performance or behavior.

Usage Example

Since `py.typed` is a marker file, its usage is implicit:

1. When you install a package that includes py.typed, your type checker automatically detects the package as typed.

2. You can then use the package in your Python code with full type checking support, e.g.:

from orjson import dumps, loads

data = {"key": "value"}
json_bytes: bytes = dumps(data)
parsed_data: dict = loads(json_bytes)

Here, the type checker understands the types of `dumps` and `loads` because `orjson` includes `py.typed` and associated type hints.

Visual Diagram

Since `py.typed` is a simple marker file without classes or functions, a flowchart representing its role in the packaging and type checking workflow is appropriate:

flowchart TD
    A[Python Package Directory] --> B[Contains py.typed file]
    B --> C[Package marked as typed]
    C --> D[Type Checkers recognize typing info]
    D --> E[Static analysis & autocompletion enabled]
    A --> F[Includes .pyi files or inline annotations]
    F --> D
    style B fill:#f96,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px
    style D fill:#afa,stroke:#333,stroke-width:2px
    style E fill:#dfd,stroke:#333,stroke-width:2px

Summary

References

• PEP 561 – Distributing and Packaging Type Information

• mypy documentation on PEP 561

This minimal but crucial file ensures that the `orjson` Python package is recognized as typed, enabling developers and tools to benefit from the comprehensive type annotations and improving code correctness and developer productivity.