type_enforced

type_enforced is a blazing-fast runtime type enforcement library for Python 3.11 and later, designed to enhance the safety and reliability of code through rigorous validation of type annotations. By eliminating external runtime dependencies and offering uncompromising performance, it provides a robust solution for developers looking to enforce type safety without sacrificing speed.

Features

• Guaranteed Complete Validation: Validates every single item across large collections and nested data structures by default with zero shortcuts.
• Faster Than the Alternatives: Outperforms Beartype, Pydantic, Typeguard, and other runtime validators. It runs up to 15x faster than Beartype on sampled checks and up to 40x faster than Pydantic on full validation.
• Flexible Validation Modes: Choose between exhaustive full validation (@Enforcer) or near instant O(1) sampled validation (@FastEnforcer with 'first', 'last', 'bookend', 'log', or percentage sampling).
• Zero Dependencies & Pure Python Compatible: Zero external runtime dependencies. Runs everywhere standard Python runs, with automatic C++ acceleration via nanobind when available and pure Python fallback.
• Rich & Modern Type Support: Comprehensive support for Python 3.11+ unions (|), nested generics, Literal, Self, TypedDict, NewType, TypeGuard/TypeIs, Callable, dataclasses, and custom Constraint rules.
• Clean Tracebacks: Pinpoints the exact line in user code causing a type mismatch by stripping internal library frames.

Why Use type_enforced?

Static type checkers (like mypy or pyright) catch errors during development, but offer zero protection at runtime against dynamic payloads, untyped API responses, or user data.

Existing runtime type checkers force an unnecessary compromise:

• Pydantic provides thorough validation but introduces heavy runtime overhead.
• Beartype is fast only by taking shortcuts (checking 1 element) and misses invalid items in unsampled data.
• Typeguard and others introduce substantial execution slowdowns.

type_enforced eliminates this compromise by delivering both the fastest full validation and the fastest sampled validation across Python.

Usage Example

Easily enforce functions, methods, classes, or entire modules:

import type_enforced

# Complete validation (validates all items in collections)
@type_enforced.Enforcer
def greet(name: list[str], repeat: int = 1) -> str:
    return f"Hello {', '.join(name)}!" * repeat

greet(["Alice"], 2)       # Returns "Hello Alice!Hello Alice!"
greet(["Alice"], "twice")  # Raises TypeError

# Fast O(1) sampled validation
@type_enforced.FastEnforcer
def process_tags(tags: list[str]) -> int:
    return len(tags)

# Enforce an entire module in a single line
import my_package
type_enforced.ModuleEnforcer(my_package)

Performance Comparison

Added differential validation overhead in nanoseconds (ns). Note: lower is better:

• Sampled Validation: type_enforced.FastEnforcer is up to ~15x faster than Beartype.
• Full Validation: type_enforced.Enforcer is up to ~40x faster than Pydantic on scalars and up to ~20x faster on nested collections, while outperforming Typeguard by orders of magnitude.

Supported Type Annotations

• Built-in Types & Unions: int, str, float, bool, int | str, int | None.
• Collections & Nested Generics: list[int], dict[str, list[int]], set[str], tuple[int, ...], etc.
• Modern PEP Constructs: Self, TypedDict, NewType, LiteralString, NoReturn, TypeGuard/TypeIs, TypeVar.
• Classes, Callables & Dataclasses: Custom classes and inheritance, type[Class], Callable[[int, str], bool], and @dataclass.
• Value Constraints: Post-type-check numeric bounds (Constraint(ge=0, le=100)), regex patterns (Constraint(pattern=...)), and custom lambda predicates (GenericConstraint).

In summary, type_enforced stands as the fastest and most flexible runtime type enforcer for Python, giving you airtight runtime safety without the performance penalty.