Skip to main content

enforce-type

Independent pure-Python compiled validation for ordinary type annotations. Python 3.14+, no runtime dependencies, no required model base class.

Version 0.2.0 adds constraints and opt-in coercion to the core validation operations. Validation remains strict unless coercion is explicitly selected.

python -m pip install enforce-type==0.2.0
from dataclasses import dataclass
from enforce_type import compile_type

@dataclass
class User:
    name: str
    age: int
    active: bool = True

users = compile_type(User)
user = users.load({"name": "Ella", "age": 34})
assert users.check(user) is user
assert users.dump(user) == {"name": "Ella", "age": 34, "active": True}
assert users.load_partial({"active": False}) == {"active": False}

Compile at application setup, then reuse the plan. Annotation resolution happens during compilation; value operations execute immutable nodes with their own invocation-local scratch state. Plans can be shared across concurrent callers. Version 0.2.0 provides a synchronous engine; async I/O rules and bounded async batches are future work. No thread or event loop starts automatically.

Four explicit operations

Operation Contract
check(value) Validate a native Python value and return that same object.
load(data, mode="json") Validate decoded data and construct Python values.
dump(value, mode="json") Validate native values and serialize supported data.
load_partial(data, mode="json") Validate supplied dataclass fields and return a change dictionary.

load and dump also accept mode="python". The default JSON mode operates on decoded Python data; it does not parse JSON text or enforce HTTP/media/body rules. check always validates native Python types without conversion. Optional scalar loading conversions require compile_type(..., coerce=True) as documented below. Mutable dataclass assignments are not automatically enforced; call a plan at the desired boundary.

from uuid import UUID

identity = compile_type(UUID)
value = identity.load("00000000-0000-0000-0000-000000000001")
assert identity.dump(value) == "00000000-0000-0000-0000-000000000001"
assert identity.load(value, mode="python") is value

point = compile_type(tuple[float, float])
assert point.load([12.5, 17.2]) == (12.5, 17.2)

Supported types and modes

Annotation Native Python JSON load / dump
str, bool, int, None Exact primitive types Same, with valid Unicode strings
float Actual finite float Load finite integer/float numbers; dump a native float
UUID Actual UUID UUID string representation
Enum Actual member Finite primitive member value
Literal Type-sensitive choices, including supported enum members Corresponding value representation
Union / nullable First successful compiled branch Same, with branch-specific construction
list[T] Built-in list Array / list
tuple[A, B], tuple[T, ...] Fixed or variadic built-in tuple Array / list
dict[K, V] Built-in dictionary with supported scalar keys Keys must actually be strings
dataclass Instance with valid declared fields Construct from / serialize to a field dictionary

Primitive rules are strict by default. True does not pass for int, and "42" does not become an integer. A native float contract rejects integer objects during check, Python-mode load, and dump. JSON loading accepts an integer number for a float field and returns a float. NaN and infinity are rejected in every mode.

Python-mode load requires native UUIDs, enums and tuples; it can also construct dataclasses from dictionaries. Python-mode dump turns dataclasses into dictionaries while retaining native UUIDs/enums/tuples. Loading/dumping containers creates new containers. Existing native dataclass instances supplied to Python-mode load are validated and returned unchanged; this is not a general deep-copy facility.

Dictionary keys are always type-checked without conversion, preventing entry collisions. Thus dict[int, str] works in Python mode but cannot load {"1":"x"} as an integer-keyed dictionary or dump integer keys to JSON. Dynamic key names are omitted from errors. Python strings may contain surrogates; JSON load/dump rejects them. Union branch errors remain isolated and unsuccessful branches collapse into one stable union issue. Ambiguous unions use the order exposed by Python's typing system; prefer unambiguous contracts.

Unsupported annotations raise SchemaError at compilation. The initial release rejects Any, bare containers, empty-tuple annotations, sets, abstract collections, TypedDict, TypeVar/generic models, PEP 695 alias objects, NewType, Callable/Protocol, recursive models and conversions beyond the explicit scalar table below. Assignment aliases that already resolve to supported types work. There is no implicit Any fallback.

Ordinary dataclasses

Nested, inherited, frozen, slots and keyword-only dataclasses work. fields is an immutable tuple of FieldInfo(name, annotation, required, init, has_default_factory) descriptions. ClassVars and properties are not fields. Subclasses are accepted during instance checking, but dump includes only the fields declared by the compiled model.

Defaults/factories run through ordinary construction and the complete result is validated after __post_init__. Invalid supplied fields prevent that model's construction. init=False fields are checked/dumped after construction and reject input; they need to be populated by the model. InitVars, class-wide init=False and incompatible constructor signatures are unsupported.

Constructors, factories and attribute access are application code. Keep them fast and free of external side effects; validation cannot roll back those effects. Ordinary failures become value-free issues. Control-flow BaseExceptions propagate. Compile trusted schemas only: resolving annotations can execute Python code.

Partial loading does not construct the root model, run its factories, supply omitted defaults, assign attributes, or enforce cross-field constructor invariants. Supplied nested models are complete values and can apply their own defaults. Applying changes and validating the resulting object remain caller responsibilities:

from dataclasses import replace

changes = users.load_partial({"active": False})
updated = replace(user, **changes)
users.check(updated)

Annotation constraints

Use immutable Min, Max and Length rules with typing.Annotated:

from typing import Annotated
from enforce_type import Length, Max, Min

quantity = compile_type(Annotated[int, Min(0), Max(999)])
name = compile_type(Annotated[str, Length(min=1, max=100)])
assert quantity.load(12) == 12
assert name.check("Ella") == "Ella"

Min and Max are inclusive finite numeric bounds for int or float. Length(min=0, max=None) counts Unicode code points for strings and entries for supported lists, tuples and dictionaries. Rules apply to every operation, including nested values, dictionary keys, defaults and post-init results. Bounds apply to native values after JSON conversion. Length failures prevent element construction; configured item limits still take precedence. Annotated wrappers do not consume extra runtime depth.

Rules compose in declaration order. Invalid configurations, contradictory bounds, inapplicable rules and unknown Annotated metadata raise SchemaError at compile time. Apply rules inside nullable/union branches, such as Annotated[int, Min(0)] | None. Error codes are min, max, min_length and max_length, with static expected-type labels that omit inputs and bounds.

Ordinary dataclass fields also accept namespaced rules:

from dataclasses import field

@dataclass
class Stock:
    quantity: int = field(metadata={"enforce_type": {"min": 0, "max": 999}})
    name: str = field(metadata={"enforce_type": {"min_length": 1, "max_length": 100}})

The namespace accepts a built-in dictionary or MappingProxyType with only min, max, min_length and max_length keys. An empty mapping adds no rules. Metadata constraints compose with Annotated constraints, which run first; metadata numeric rules then run in min/max order, followed by length rules. Compilation snapshots the configuration, so later metadata edits do not change an existing plan. The same rules validate supplied partial fields, defaults, factories, post-init results and computed init=False fields. Partial loading still does not construct the root model or fill omitted fields.

An id is an ordinary field. Persistence, immutable identities, authorization and read/write visibility are caller-owned policies. All declared fields are included in dump. Unrelated dataclass metadata is ignored; unsupported keys or malformed configuration in the enforce_type namespace raise SchemaError.

Explicit scalar loading conversions

counts = compile_type(Annotated[int, Min(0)], coerce=True)
assert counts.load("42") == 42
assert counts.load("42", mode="python") == 42

coerce must be an actual boolean and defaults to False. When enabled it applies to scalar values throughout load and supplied load_partial fields in either mode. check and dump always require native values. Defaults, factory results, post-init fields and existing Python-mode dataclass instances are checked strictly. Constraints run after scalar conversion.

Target Additional accepted inputs with coerce=True
int ASCII decimal strings with an optional +/- sign, including leading zeros
float Native integers or ASCII decimal/exponent strings such as "1", "-.5", "1.", "2e3"
bool Exactly "true" and "false"
Other types No additional conversions

Finite-float rules still apply, including overflow after conversion. Float rounding and underflow follow Python's ordinary float behavior. Integer text conversion respects Python's configured decimal-digit limit; conversion failures produce value-free coercion issues. Non-finite float results produce finite.

Whitespace, underscores, non-ASCII digits, hexadecimal numbers, named infinity/NaN, float-to-int truncation, number/bool interchange and arbitrary object conversion callbacks are refused. String/numeric subclasses are not converted. Containers keep their existing Python/JSON representation rules. Dictionary keys are always checked without conversion. UUIDs, enums and None keep their existing mode rules.

Unions still select the first successful branch in Python typing order, including each branch's enabled conversions and constraints. For example, int | str can load "12" as 12, while str | int preserves "12". Literal choices use the same scalar conversions followed by type-sensitive choice matching. Use unambiguous contracts when a serialized string must retain its type.

Structured errors and bounds

from enforce_type import Limits, ValidationError, compile_type

counts = compile_type(list[int], limits=Limits(max_items=100, max_errors=2))
try:
    counts.load(["wrong"])
except ValidationError as error:
    assert error.issues[0].as_dict() == {
        "path": [0], "code": "type", "expected": "int"
    }

Issues are immutable, ordered data: path, code and a static expected-type label. Messages/issues omit submitted values and unknown or dynamic dictionary keys; dictionary paths use "*". Python tracebacks remain normal Python tracebacks, so applications should not expose traceback locals to clients.

Codes include type, missing, unknown_field, init_field, length, finite, uuid, unicode, enum, literal, union, json_key, depth, collection_size, construction and attribute. Invalid schema/configuration raises SchemaError separately. Constraint codes are min, max, min_length, max_length; explicitly enabled scalar text conversions also use coercion.

Default limits are depth 32, 1,000 entries per container or full-model fields, and 20 issues per call. Oversized structures fail before element traversal; reaching the issue cap stops further work. Partial input limits apply to supplied fields. Compilation has a separate 64-level type-graph bound, including reused subtrees. Bounds do not limit already allocated input bytes, total application memory, or arbitrary constructor execution. Do not mutate shared inputs/model definitions while another call is validating them. User factories are responsible for their own thread safety. Threaded reuse is verified; CPU speedups are not claimed.

Development

uv sync --locked
uv run --frozen python examples/users.py
uv run --frozen python -W error::ResourceWarning -m unittest discover -s tests -v
uv run --frozen python scripts/check_distribution.py

CI tests Linux, macOS and Windows/Python 3.14. Distribution checks use exact allowlists, verify metadata and zero runtime requirements, rebuild the source distribution, and run independent wheel/source installations outside the checkout. Release publishing uses release.yaml, environment pypi and OIDC; verified artifacts are the exact uploaded files.

The Project and issues track broader typing, async rules/batches, function enforcement and JSON Schema. The package remains independent of expose-api and its validation infrastructure. The selected optional expose-api adapter contract keeps resource policy in expose-api and reuses the published synchronous value APIs. License terms have not yet been specified.

Metadata

Release files for enforce-type 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for enforce-type 0.2.0
File Size Uploaded Provenance Actions
enforce_type-0.2.0.tar.gz 13.6 kB With provenance Details for enforce_type-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for enforce-type 0.2.0
File Interpreter ABI Platform Actions
enforce_type-0.2.0-py3-none-any.whl Python 3 none any Details for enforce_type-0.2.0-py3-none-any.whl

Total release size: 30.6 kB

Release files / enforce_type-0.2.0.tar.gz

Download URL enforce_type-0.2.0.tar.gz
Size 13.6 kB
Tags Source
SHA-256 checksum
How to use checksums
92514ea428418e7a5820a4e06a2f1edb43ea34c5c7bdd08598dbdb36cdd4aa78
BLAKE2b-256 checksum
How to use checksums
3fe78c7b802f724cd2d70fb66ba46db766273f8780321f938df3ddf162a8feca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / enforce_type-0.2.0-py3-none-any.whl

Download URL enforce_type-0.2.0-py3-none-any.whl
Size 16.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9009c8576714e9b1b8a413b9c8d6483531dadd487dc84593bc064d76cdfa8d8c
BLAKE2b-256 checksum
How to use checksums
5e28d921c0b64bc33ccd8da2725ae412edcaef3baaaeaf704854daf6be0b6865
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for enforce-type 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for enforce_type-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page