type_enforced

Fast where it counts, thorough where it matters. Runtime validation for Python type annotations. Zero dependencies and uncompromising performance.

Table of Contents

• Quick Start
• Why type_enforced?
  • Performance at a Glance
• Installation
  • Requirements & Build Options
• Usage Guide
  • 1. Functions and Methods
  • 2. Classes and Dataclasses
  • 3. Module-Level Enforcement
• Supported Type Annotations
• Value Validation with Constraints
• Configuration Reference
  • Configuration Options in Depth
• Production Best Practices
• Contributing
• Academic Citation
• License

Quick Start

import type_enforced

# 1. Complete validation
@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 at runtime!

# 2. Fast O(1) validation (does not check every item in passed collections)
@type_enforced.FastEnforcer
def process_tags(tags: list[str]) -> int:
    return len(tags)

process_tags(["admin", "user"])  # Returns 2
process_tags([123, "user"])       # Raises TypeError (first element is checked)

Enforce an entire module (complete or fast O(1) sampled validation):

import my_package
import type_enforced

# Enforce all functions and classes across my_package
type_enforced.ModuleEnforcer(my_package)

# Or for fast O(1) sampled validation across my_package:
# type_enforced.FastModuleEnforcer(my_package)

Why type_enforced?

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

Existing runtime type checkers force an unnecessary compromise:

• Pydantic provides thorough validation, but comes with heavy runtime overhead and steep execution slowdowns.
• Beartype achieves high speed primarily by taking shortcuts. It samples 1 element in collections and misses invalid items in unsampled data.

type_enforced eliminates this compromise:

• Guaranteed Complete Validation: Validates every single item across large collections and nested data structures (e.g. list[dict[str, int]] or dicts with 10,000+ keys) by default, with zero shortcuts.
• Fastest Full Validation: Delivers full, uncompromising validation at a fraction of other packages' overhead.
• Fastest Sampled Validation: Need O(1) or logarithmic sampling for massive collections? This is how Beartype works. Set iterable_sample_pct='first', 'last', 'bookend', 'bookend_plus', 'log', 0 (random pick), or a percentage. Sampled validation in type_enforced runs up to ~15x faster than Beartype.
• Zero Dependencies & Pure Python Compatible: Zero external runtime dependencies. Runs everywhere standard Python 3.11+ runs, with optional automatic C++ acceleration via nanobind when available.
• Rich Type Support & Constraints: Seamlessly supports standard Python | unions, nested generics, Literals, Callables, Dataclasses, custom class inheritance, and custom validation Constraint rules.
• Clean Tracebacks: Strips internal validation frames from tracebacks by default, pinpointing the exact line in your code that caused the issue.

Performance at a Glance

Timings represent the added differential validation time (enforced call time minus non-enforced baseline call time) in microseconds (µs), averaged over 100 runs when using the C++ backend. ⚠ = checker did not consistently catch invalid types for this case (generated by utils/minibench.py). For full benchmarks see utils/benchmark.py and benchmark.md.

Sampled Validation: When 1 sample validation is acceptable, type_enforced.FastEnforcer is up to ~15x faster than Beartype.

Full Validation: When full validation is required, type_enforced.Enforcer is up to ~40x faster than Pydantic on scalars and up to ~20x faster on larger data structures.

Installation

Install via pip:

pip install type_enforced

Or using uv:

uv add type_enforced

Requirements & Build Options

• Python 3.11+

• Zero Runtime Dependencies: Self-contained package with zero external runtime dependencies.

• C++ Acceleration: If available, type_enforced leverages high-performance C++ validators via nanobind.

• Pure Python Fallback: If compiling from source on a system without a C++ compiler, type_enforced automatically falls back to a pure-Python engine.

• Force Pure Python Fallback: To explicitly skip C++ compilation and force pure Python mode:

  uv (in pyproject.toml):

  [tool.uv]
  no-binary-package = ["type-enforced"]
  config-settings-package = { type-enforced = { "cmake.define.SKIP_CPP_BUILD" = "ON" } }
  

  pip (in pyproject.toml when building from source):

  [tool.scikit-build.cmake.define]
  SKIP_CPP_BUILD = "ON"
  

  pip (in requirements.txt):

  type_enforced --config-settings=cmake.define.SKIP_CPP_BUILD=ON --no-binary type_enforced
  

  pip (CLI):

  pip install type_enforced --no-binary type_enforced -Ccmake.define.SKIP_CPP_BUILD=ON
  

  (Or set SKBUILD_CMAKE_ARGS="-DSKIP_CPP_BUILD=ON" and PIP_NO_BINARY="type_enforced" in your environment)

• Verify C++ Acceleration Status: Check whether C++ acceleration is active in the current environment:

  import type_enforced
  
  print(type_enforced.has_cpp())  # True if C++ acceleration is active, False for pure Python
  

Usage Guide

1. Functions and Methods

Apply @type_enforced.Enforcer or @type_enforced.FastEnforcer to any callable. It validates positional arguments, keyword arguments, default parameters, and the return type.

import type_enforced

@type_enforced.Enforcer
def process_user(user_id: int, tags: list[str], active: bool = True) -> dict[str, str | int]:
    return {"user_id": user_id, "status": "active" if active else "inactive"}

# Passing invalid types raises a descriptive TypeError:
process_user("123", ["admin"])
# TypeError: TypeEnforced Exception (process_user): Type mismatch for typed variable `user_id`.
# Expected one of the following `[<class 'int'>]` but got `<class 'str'>` with value `123` instead.

2. Classes and Dataclasses

Decorating a class with @type_enforced.Enforcer or @type_enforced.FastEnforcer automatically enforces types on all annotated methods (including __init__, @classmethod, and @staticmethod):

import type_enforced
from dataclasses import dataclass

@type_enforced.Enforcer
class Account:
    def __init__(self, username: str, balance: float):
        self.username = username
        self.balance = balance

    def deposit(self, amount: float) -> float:
        self.balance += amount
        return self.balance

    @staticmethod
    def validate_code(code: str) -> bool:
        return len(code) == 6

# Dataclasses work seamlessly:
@type_enforced.Enforcer
@dataclass
class UserConfig:
    retries: int
    endpoint: str

To disable enforcement on a specific method within an enforced class:

@type_enforced.Enforcer
class Worker:
    def standard_job(self, task: str) -> None:
        pass

    @type_enforced.Enforcer(enabled=False)
    def high_throughput_job(self, data):
        # Type enforcement skipped for maximum throughput
        pass

3. Module-Level Enforcement (ModuleEnforcer or FastModuleEnforcer)

Enforce typing across an entire module in a single line without decorating every function and class individually:

# Place at the top of your module file (e.g., my_package/core.py)
import type_enforced

type_enforced.ModuleEnforcer()      # Complete validation across module
# Or for fast O(1) sampled validation across the module:
# type_enforced.FastModuleEnforcer()

def add(a: int, b: int) -> int:
    return a + b

class Helper:
    def run(self, flag: bool) -> str:
        return "ok" if flag else "failed"

You can also enforce an imported module:

import my_package
import type_enforced

type_enforced.ModuleEnforcer(my_package)
# Or: type_enforced.FastModuleEnforcer(my_package)

Note: By default, submodules=True, which recursively enforces all sub-packages/sub-modules in the same namespace (e.g. mypkg.submodule), while safely ignoring third-party and standard library imports.

Supported Type Annotations

type_enforced supports all standard Python 3.11+ typing constructs:

Standard Built-ins & Unions

@type_enforced.Enforcer
def fn(
    a: int,
    b: str | float,                    # Standard union syntax
    c: int | None = None,              # Optional syntax
) -> None:
    pass

Collections & Nested Generics

@type_enforced.Enforcer
def fn(
    items: list[int | float],
    mapping: dict[str, list[int]],      # Dicts require [KeyType, ValType]
    unique_ids: set[str],
    fixed_pair: tuple[str, int],        # Exact positional tuple: (str, int)
    var_tuple: tuple[int, ...],         # Variable-length tuple
) -> None:
    pass

Custom Classes & Subclass Inheritance

By default, subclasses pass type validation (e.g. Bar() satisfies Foo if class Bar(Foo)):

class Animal: pass
class Dog(Animal): pass
class Vehicle: pass

@type_enforced.Enforcer
def feed(animal: Animal) -> None:
    pass

feed(Animal())  # OK
feed(Dog())     # OK (subclasses allowed)
feed(Vehicle()) # Raises TypeError

To enforce uninitialized class objects (the class itself, rather than an instance), use type[Animal] (or typing.Type[Animal]):

@type_enforced.Enforcer
def make_instance(cls: type[Animal]) -> Animal:
    return cls()

Literals & Special Types

from typing import Literal, Callable, Sized, Any

@type_enforced.Enforcer
def fn(
    mode: Literal["read", "write"],        # Value check: must equal "read" or "write"
    handler: Callable,                     # Functions, methods, generators
    container: Sized,                      # list, dict, set, str, tuple, bytes, etc.
    wildcard: Any,                         # Permissive bypass
) -> None:
    pass

• Stacking Literals: Literals combine with unions using OR logic (int | Literal['auto'] allows any int or the literal string 'auto').

Modern Typing Constructs (PEP Standards)

type_enforced comprehensively supports modern typing features from recent Python PEPs:

from typing import (
    Callable,
    LiteralString,
    Never,
    NewType,
    NoReturn,
    Self,
    TypeGuard,
    TypeIs,
    TypeVar,
    TypedDict,
)

# 1. PEP 673: typing.Self
class Builder:
    @type_enforced.Enforcer
    def set_name(self, name: str) -> Self:
        self.name = name
        return self

# 2. PEP 589: typing.TypedDict (validates required keys & field types)
class UserPayload(TypedDict):
    id: int
    name: str

@type_enforced.Enforcer
def create_user(payload: UserPayload) -> str:
    return payload["name"]

# 3. PEP 484: typing.NewType
UserId = NewType("UserId", int)

@type_enforced.Enforcer
def get_user(user_id: UserId) -> None:
    pass

# 4. Subscripted Callables (PEP 484 & PEP 612)
@type_enforced.Enforcer
def apply_handler(callback: Callable[[int, str], bool]) -> None:
    pass

# 5. PEP 675: typing.LiteralString
@type_enforced.Enforcer
def run_query(sql: LiteralString) -> None:
    pass

# 6. PEP 484 / PEP 654: NoReturn and Never
@type_enforced.Enforcer
def terminate() -> NoReturn:
    raise SystemExit(0)

# 7. PEP 647 & PEP 742: TypeGuard and TypeIs
@type_enforced.Enforcer
def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

# 8. TypeVar, ParamSpec, TypeVarTuple & PEP 695 (Python 3.12+)
T = TypeVar("T", bound=int | float)

@type_enforced.Enforcer
def scale(val: T, factor: float) -> float:
    return val * factor

Collection & Nested Type Unions

Unions of collection types are evaluated per-variant, enforcing that each container strictly satisfies one schema rather than allowing mixed elements:

@type_enforced.Enforcer
def process_data(
    coords: tuple[int, str] | tuple[str, int],
    lookup: dict[str, list[int]] | dict[str, int],
    tags: list[int] | list[str],
) -> None:
    pass

# Distinct collection schemas match:
process_data((1, "north"), {"a": [1, 2]}, [1, 2, 3])  # OK
process_data(("north", 1), {"a": 10}, ["a", "b"])  # OK

# Mixed invalid structures fail:
process_data((1, 1), {"a": 10}, [1, 2])  # Raises TypeError for coords
process_data(
    (1, "north"), {"a": 1, "b": [2]}, [1, 2]
)  # Raises TypeError for lookup
process_data((1, "north"), {"a": 10}, [1, "two"])  # Raises TypeError for tags

Variadic Positional & Keyword Arguments

*args and **kwargs are fully supported with clear, indexed error messages:

@type_enforced.Enforcer
def configure(*flags: str, **settings: int | bool) -> None:
    pass

configure("verbose", "debug", timeout=30, dry_run=True)  # OK
configure("verbose", 123)  # Raises TypeError: Type mismatch for typed variable `flags[1]`
configure(timeout="30s")   # Raises TypeError: Type mismatch for typed variable `settings['timeout']`

Known Limitations / Currently Unsupported

• Generic parameterization of Sized (e.g. Sized[int] — use Sized without inner type arguments)

Value Validation with Constraints

type_enforced allows post-type-check value constraints directly in type annotations.

Built-in Constraint

Validate bounds, numeric comparisons, string patterns (regex), and inclusion/exclusion:

import type_enforced
from type_enforced.utils import Constraint

@type_enforced.Enforcer
def set_score(
    score: int | Constraint(ge=0, le=100),
    code: str | Constraint(pattern=r"^[A-Z]{3}[0-9]{4}$"),
) -> bool:
    return True

set_score(85, "ABC1234")    # Passes
set_score(105, "ABC1234")   # Raises TypeError (Constraint `Less Than Or Equal To (100)` not met)
set_score(85, "invalid")    # Raises TypeError (Constraint `Regex Pattern Match` not met)

Available Constraint parameters:

• gt, lt, ge, le, eq, ne (numeric / comparison bounds)
• pattern (regular expression string match)
• includes, excludes (membership checks)

Custom GenericConstraint

Write arbitrary validation logic using custom predicates:

import type_enforced
from type_enforced.utils import GenericConstraint

RGBColor = str | GenericConstraint({
    "valid_hex_color": lambda c: c.startswith("#") and len(c) in (4, 7)
})

@type_enforced.Enforcer
def render(color: RGBColor) -> None:
    pass

render("#ffffff")  # Passes
render("red")      # Raises TypeError (Constraint `valid_hex_color` not met)

Note: Constraints are evaluated after type checking. Constraints stack with unions: int | Constraint(ge=0) | Constraint(le=10).

Configuration Reference

@Enforcer, @FastEnforcer, ModuleEnforcer, and FastModuleEnforcer accept the following configuration arguments:

Configuration Options in Depth

1. Strict Typing Mode (only_typed=True)

To catch unannotated parameters or missing return annotations across your codebase, enable only_typed=True. This raises a TypeError at definition time if any parameter (excluding self/cls) or the return type lacks an annotation:

import type_enforced

@type_enforced.Enforcer(only_typed=True)
def calculate(a: int, b: int) -> int:
    return a + b

# Missing annotation on parameter `b` or missing return annotation raises immediately:
@type_enforced.Enforcer(only_typed=True)
def invalid_fn(a: int, b):
    return a
# TypeError: TypeEnforced Exception (invalid_fn): Untyped variable `b` found in function/method `invalid_fn`.

2. Warning Mode (strict=False)

Print warnings to the console instead of raising exceptions (useful for gradual adoption or debugging without breaking execution):

@type_enforced.Enforcer(strict=False)
def lenient_fn(x: int) -> int:
    return x

lenient_fn("not_an_int")
# Logs: TypeEnforced Warning (lenient_fn): Type mismatch for typed variable `x`...
# Returns "not_an_int" without raising an exception.

3. Clean Tracebacks (clean_traceback=True)

By default, clean_traceback=True temporarily hooks sys.excepthook when a type exception is raised, stripping internal type_enforced library frames so that unhandled script tracebacks point directly to the line of user code that caused the issue.

Note on Interactive Terminals / REPLs: In interactive environments (such as the Python REPL / PyREPL, IPython, or Jupyter notebooks), the shell wraps execution in an internal try...except loop and catches exceptions before they reach sys.excepthook. Consequently, interactive terminal sessions will still display the full traceback.

4. Sampled Validation (FastEnforcer, FastModuleEnforcer, iterable_sample_pct)

For large or performance-critical collections, use @type_enforced.FastEnforcer or configure sampling instead of full iteration:

• 'first' (default for FastEnforcer / FastModuleEnforcer): Validates the first element in O(1) time (runs up to ~15x faster than Beartype).
• 'last': Validates the last element in O(1) time for indexable sequences (list, tuple). For non-indexed collections like dict and set, 'last' validates the first item to avoid reverse iteration and hash table lookup overhead.
• 'bookend': Validates the first and last elements in O(1) time for sequences (the first 2 items for dict and set).
• 'bookend_plus': Validates the first, last, and a random middle element in O(1) time for sequences (the first 2 items and 1 random item for dict and set).
• 'log': For sequences (list, tuple), samples ceil(log2(n)) items by picking a Weyl pseudo-random start offset and taking even step jumps across the collection. For dict and set, validates the first ceil(log2(n)) items.
• 0: Validates one element chosen at random.
• 1..99 (int, Enforcer / ModuleEnforcer only): Validates the specified percentage of items (rounding up). For sequences, selects a Weyl pseudo-random start offset in [0, step - 1] and takes even step jumps across the collection, giving every index an equal probability of being checked. For dict and set, validates the first N items.
• 100: Complete validation of all items across the collection.

# Using FastEnforcer directly:
@type_enforced.FastEnforcer
def fast_check(items: list[int]) -> int:
    return len(items)

fast_check([1, 2, 3])           # OK
fast_check(["bad_first", 2, 3])  # Raises TypeError

# Or configure Enforcer with a specific sample mode:
@type_enforced.Enforcer(iterable_sample_pct="last")
def check_last(items: list[int]) -> int:
    return len(items)

Production Best Practices

Multi-Threaded Services & Web Frameworks (clean_traceback=False)

By default, clean_traceback=True temporarily hooks sys.excepthook to filter internal library frames for standalone scripts. In concurrent multi-threaded environments and applications using centralized error handlers, consider setting clean_traceback=False:

import type_enforced

@type_enforced.Enforcer(clean_traceback=False)
def process_request(user_id: int, tags: list[str]) -> dict:
    return {"user_id": user_id, "tags": tags}

Contributing

Contributions are welcome!

Development Setup

We use uv for dependency management and testing in a Unix-based environment (Linux, macOS, or WSL2 on Windows).

# Clone the repository
git clone https://github.com/connor-makowski/type_enforced.git
cd type_enforced

# Install dev dependencies
uv sync --extra dev

Development Commands

Guidelines

1. Fork the repo and create your branch from main.
2. Ensure all tests pass across versions (uv run nox).
3. Format code before committing (uv run python utils/prettify.py).
4. Keep commits atomic and clearly described.
5. Submit a pull request.

Academic Citation

If you use type_enforced in academic research, please cite our JOSS paper:

@article{Makowski2026,
  doi = {10.21105/joss.08832},
  url = {https://doi.org/10.21105/joss.08832},
  year = {2026},
  publisher = {The Open Journal},
  volume = {11},
  number = {118},
  pages = {8832},
  author = {Connor Makowski},
  title = {type_enforced: A pure Python runtime type enforcer},
  journal = {Journal of Open Source Software}
}

License

Distributed under the MIT License. See LICENSE for details.