Skip to content

What a validator cannot do

Every entry here is a deliberate boundary rather than an unfinished feature. They come from two places: what a runtime check can observe at all, and what this library decided not to be. Knowing which is which tells you whether to wait for it, work around it, or use another tool — so each says which it is.

The neighboring pages cover two nearby questions: resource limits is what a value cannot make the validator do, and the decidability boundary is what the comparison operators cannot yet prove. This page is about the shape of the product.

It does not convert

A validator answers whether the object you already hold is a member of a set. It never copies, coerces, or returns a different value: "1" is not an int, a missing key is not filled from a default, and no field is renamed on the way through. ensure returns its argument — the same object, so is holds.

This is the product decision the rest of the library rests on. A tool that converts is answering a different question, and there are good ones; reach for one when the input is a wire format you need to become a domain object.

from valgebra import Validator

numbers = Validator(int)
value = 1
assert numbers.ensure(value) is value  # the same object, not a copy
assert not numbers.is_valid("1")  # a string that looks like one is not one

It does not read the future of a value

The check is a decision about a value at one moment. A value that is mutated afterwards is not re-checked, and nothing is frozen: validating a list says the list's elements belonged to the set when they were read.

An observable consequence: a container whose size changes while the walk is reading it is reported rather than silently half-checked, because the alternative is an answer about a value that never existed. A change that keeps the size is not seen, and the answer is about what the walk read (error model).

It cannot look inside a callable

Callable[[int], str] names a function's domain and return, and neither is observable at runtime: no check can ask an arbitrary function what it accepts without calling it, and calling it is not a membership test. A callable schema is therefore an isinstance check for being callable, and the argument types are not checked at all.

from collections.abc import Callable

from valgebra import Validator

callables = Validator(Callable[[int], str])
assert callables.is_valid(len)  # any callable belongs
assert not callables.is_valid(3)

A Protocol's method is read the same way: the value's attribute is callable, and its parameters and return are not asked.

It reads values, not declarations

A relation is inclusion between sets of values; a static checker's assignability is a relation between declarations, and the two part where a checker reasons about what a declaration permits. A mutable member is invariant to a checker, so a class declaring count: bool is not assignable to a protocol declaring count: int. Over values every bool is an int, so the class's set is inside the protocol's, and relation_to says "subset". A TypedDict declaring x: bool is below one declaring x: int for the same reason.

from dataclasses import dataclass
from typing import Protocol

from valgebra import Validator


class Counted(Protocol):
    count: int


@dataclass
class Flag:
    count: bool


assert Validator(Flag).relation_to(Validator(Counted)) == "subset"

The same reading decides what a class's declarations cannot. An instance of a plain class annotated x: int can be given x = "s", so the class is not below a protocol of x, whatever a checker says about it. And a special method set on the instance satisfies a protocol's member as any attribute does, though len() and the other operators read it from the type.

A class is its instances at run time, which is not always what a stub says. The stubs declare that open() returns a typing.TextIO, and no stream derives from that class: isinstance(io.StringIO(), typing.TextIO) is False, so Validator(typing.TextIO) admits no stream either. The class the streams do derive from is io.TextIOBase, and that is the one to write:

import io
import typing

from valgebra import Validator

assert not Validator(typing.TextIO).is_valid(io.StringIO())
assert Validator(io.TextIOBase).is_valid(io.StringIO())

It cannot see a generic's arguments on a value

Python erases them. A list at runtime is a list of whatever it holds, so list[int] is checked by reading the elements — which is why it works — while Sequence[int] and Mapping[str, int] are refused: those name protocols whose instances need not be enumerable without consuming them, and a check that consumed an iterator would change the value it was asked about.

There is no variance and no type variable, for the same reason: a TypeVar is a statement about a relationship between uses in a program, and a runtime check sees one value.

A predicate is a black box

A Predicate refinement runs your callable. That makes it as expressive as Python — and opaque to the algebra: the complement of a predicate is not a set the library can reason about, two predicates are not compared, and a schema carrying one is answered conservatively by every relation (decidability). Predicates are the escape hatch, and using one is choosing expressiveness over decidability.

The same holds of a class whose metaclass answers isinstance by running code: what it admits is not a set that stands still, so the complement laws are not applied to it. Telling such a class from a plain one needs the class object, which construction does not consult, so construction declines the two folds for every class (denotes_a_set_within in crates/valgebra-core/src/oracle.rs): a plain class's meet with its complement keeps its spelling, and is_empty decides it empty.

That is why A & ~A is not folded to nothing when A carries a predicate or a class, and A | ~A not to the top. The laws are about sets — a value is in A or it is not, once — and the two occurrences of A there are two calls. A predicate that does not answer from the value alone answers them differently, and a value then really is admitted by the meet. The fold would be a claim the schema contradicts, so it is refused rather than approximated; a Regex folds, because a pattern is a function of the string.

Your code runs inside the check, and may call back in

A predicate, an __eq__ behind a Literal, an isinstance hook, a keys() — membership runs your code at almost every entry of a container, and while it runs the check is on the stack. That code may call valgebra again. It may build a schema, ask a decision, or re-enter the very validator that called it: the walk keeps its recursion guard in a per-call local, so a nested check is an ordinary one and does not disturb the outer.

from collections.abc import Iterable
from typing import Annotated

import annotated_types as at

from valgebra import Validator

rows = Validator({"id": int})


def every_row(value: Iterable[object]) -> bool:
    return all(rows.is_valid(row) for row in value)


page = Validator(Annotated[list, at.Predicate(every_row)])
assert page.is_valid([{"id": 1}, {"id": 2}])
assert not page.is_valid([{"id": 1}, {"id": "two"}])

What bounds it is Python's own recursion limit and the native stack, not a valgebra bound: the walk's depth guard is per call, so each re-entry starts a fresh walk on top of the frames the last one holds. On CPython a predicate that re-enters without a base case raises RecursionError, on any thread: 3.14 and later raise it at the Python frame between two calls, where the thread's stack runs short, and before 3.14 the walk reads the thread's stack before it calls a predicate and raises it there, with 32 KiB left. Before 3.14 the question is the predicate's alone: an __eq__ or an isinstance hook that re-enters is not asked. On musl neither check stands: the walk does not read the stack, whose reading for the main thread is the stack mapped so far, and CPython 3.15.2's own check ends in a segmentation fault on a thread of 128 KiB. On PyPy the process ends in PyPy's own stack check, inside cpyext, with no nesting between the calls. No check reads the walk between two calls, though, so where each re-entry walks levels of nesting near the end of the stack, the walk's own frames can run past it and the process ends: CPython 3.15 does where a predicate re-enters under sixty levels of lists on a 1 MiB thread. Give a re-entering predicate a base case, and run it on a thread of 1 MiB or more.

A fatal signal is not turned into a verdict: a base exception that is not an ordinary Exception (KeyboardInterrupt, SystemExit, GeneratorExit), and MemoryError and RecursionError, propagate, because a check that swallowed one would make the process unstoppable from inside a loop or hide the interpreter running out of a resource. The set is the one the walk page (docs/dev/walk.md) owns and the error model lists. Everything else a predicate raises is reported as predicate_error rather than as a rejected value (refinements), so a bug in your callable is not mistaken for data that failed.

The one thing your code must not do is resize the container being checked. That is not refused — it is reported: the walk reads every container against a count taken once, and a count that moved makes the reading cover no state the value was ever in, so the answer is mutated_during_validation and a non-member (error model). It applies equally to another thread on a free-threaded interpreter, which is the case that cannot be written out of a program by discipline.

It reads an array through what the array exposes

A numpy array is an instance of a class, so numpy.ndarray builds as that class and reads no element. A scalar belongs where its class derives: np.float64 subclasses float and is a float, to the relations as to the walk, and np.float32, np.int64 and np.bool_ subclass no builtin and are none of float, int and bool:

import numpy as np

from valgebra import Validator

assert Validator(np.ndarray).is_valid(np.zeros(3))
assert not Validator(list[float]).is_valid(np.zeros(3))

assert Validator(float).is_valid(np.float64(1.0))
assert Validator(np.float64).is_subtype_of(float)
assert not Validator(float).is_valid(np.float32(1.0))
assert not Validator(int).is_valid(np.int64(1))
assert not Validator(bool).is_valid(np.bool_(True))

A bound over float asks the value, so np.float64 answers it by numpy's comparison, which converts an int to a float first: the relations read a bound past 2**53 as float does, and the soundness page names the difference.

numpy's own generic reads what it names. np.ndarray[S, np.dtype[T]] denotes the instances of np.ndarray whose shape is in S and whose elements are T's, read by the kind and the width of its dtype. So a byte order is storage and reads alike, and np.int64 and np.longlong are one element where the platform makes them one width. The width is read where the validator is built, so np.long, 8 bytes on 64-bit Linux and 4 on 64-bit Windows, is a different set on each, and an array that crosses keeps the width it has: write np.int32 where arrays cross platforms. Any in either place asks nothing, a shape is a tuple or a union of tuples, and an abstract scalar type such as np.floating is refused, since np.dtype makes no dtype of it. The relations decide what it says:

from typing import Literal

import numpy as np
import numpy.typing as npt

from valgebra import Validator, intersection

rows_of_three = Validator(np.ndarray[tuple[int, Literal[3]], np.dtype[np.float64]])
assert rows_of_three.is_valid(np.zeros((4, 3)))
assert rows_of_three.is_valid(np.zeros((4, 3), dtype=">f8"))  # whichever its byte order
assert not rows_of_three.is_valid(np.zeros((4, 4)))
assert not rows_of_three.is_valid(np.zeros((4, 3), dtype="float32"))

doubles = Validator(npt.NDArray[np.float64])
assert doubles.is_valid(np.zeros(3))
assert doubles.is_valid(np.zeros((2, 2)))
assert rows_of_three.relation_to(doubles) == "subset"
assert rows_of_three.relation_to(np.ndarray) == "subset"
assert intersection(doubles, npt.NDArray[np.float32]).is_empty()

# A refutation names a value, and no decider builds an array.
assert doubles.relation_to(rows_of_three) == "undecided"

A set that form does not name, floating elements of any width, is a Protocol over the same attributes, met with the class:

from typing import Literal, Protocol

import numpy as np

from valgebra import instance_of, intersection


class FloatKind(Protocol):
    kind: Literal["f"]


class FloatElements(Protocol):
    dtype: FloatKind


floats = intersection(instance_of(np.ndarray), FloatElements)
assert floats.is_valid(np.zeros(3, dtype=">f8"))
assert floats.is_valid(np.zeros(3, dtype="float32"))
assert not floats.is_valid(np.zeros(3, dtype="int64"))

The elements are not read. An element is no attribute, so a set over them is a predicate: exact on membership, and every relation that looks inside it declines.

An order bound on an array holds one-element arrays alone. Annotated[np.ndarray, Ge(0)] denotes the arrays for which x >= 0 holds. For an array that is an array, its truth raises unless it holds one element, and a comparison that raises does not hold. So the bound refuses np.zeros(3), every element of which is >= 0. No value is misread, and the set is not what the spelling suggests. Write the predicate:

from typing import Annotated

import annotated_types as at
import numpy as np

from valgebra import Validator

bounded = Validator(Annotated[np.ndarray, at.Ge(0)])
assert bounded.is_valid(np.zeros(1))
assert not bounded.is_valid(np.zeros(3))

non_negative = Validator(
    Annotated[np.ndarray, at.Predicate(lambda x: bool((x >= 0).all()))]
)
assert non_negative.is_valid(np.zeros(3))
assert not non_negative.is_valid(np.array([-1.0, 2.0]))
assert non_negative.relation_to(np.ndarray) == "subset"
assert Validator(np.ndarray).relation_to(non_negative) == "undecided"

Another library's array is read the same way. The spelling asks for attributes, so it holds of whatever has them, met with that library's class. No other library's array has a generic form to read:

Array shape Its elements
jax.Array, met as instance_of(jax.Array) a tuple dtype is numpy's, so kind reads as above
torch.Tensor, met as instance_of(torch.Tensor) torch.Size, a tuple subclass, which a tuple schema reads dtype has no kind: is_floating_point, is_complex and is_signed are its attributes

jaxtyping's Float[Array, "n 3"] builds as what it is, a class with an isinstance hook: membership reads its dtype and shape exactly, and every relation is undecided. The Array API's isdtype is a function, so a set over it is a predicate, and a torch.Tensor has no __array_namespace__ to ask. These were read on JAX 0.12 and PyTorch 2.15, and no lane here installs either.

Under jax.jit the attributes still read and the elements do not. A traced value is a tracer with a shape and a dtype, so a record reads it as it reads an array. A predicate over its elements raises what a tracer's truth raises, which is predicate_error, so is_valid answers False inside jit for an array it admits outside. Keep what a traced function checks to the attributes.

It does not generate, infer, or export

  • No schema inference from values or code. A schema is written, not guessed.
  • No serialization. Nothing here turns a value into JSON or back; the JSON path validates during parsing (JSON input) and produces the same accept/reject decision as the object path, not a serializer.
  • No JSON Schema import or export. The two describe different value universes — JSON has no bytes, no tuple, and no class identity — so a translation would be lossy in both directions rather than merely absent.
  • No witness. A refuted relation names no value: relation_to answers "not_subset", and no call builds a member of a schema or of a difference. Building one is a constructor per kind -- a string from a pattern, a dict from a record -- with none for a class instance or a predicate, so it would be partial by nature. A value to show is found by sampling and checked with is_valid, whose membership is exact, as inspection does it.
  • No static checking. valgebra runs; a type checker does not run it. The two are complementary, and the foundations page says where their models agree and where they part. What a checker reads from a validator, and the spellings it refuses, are on static checkers.

One operator, and it is the one typing already uses

a | b builds a union, because | is what Python's own type syntax uses for one — int | str is a union before valgebra sees it, and __ror__ is what makes None | validator work. There is no & and no ~.

That is the ship-versus-recipe rule rather than an oversight: intersection and complement are functions that already exist and say what they do, and an operator spelling for them would be a second way to write the same thing whose only argument is that it is shorter. | is not a second way to write union — it is the way the language spells it.

from valgebra import Validator, complement, intersection

assert (Validator(int) | str).is_equivalent(int | str)
assert not hasattr(Validator(int), "__and__")
assert intersection(int, str).is_empty()
assert complement(int).is_valid("x")

A validator does not pickle

It holds the classes an isinstance atom names and the callables a predicate runs, so pickling one would have to pickle those — a different question with a different answer per object. Send the schema instead and rebuild on the other side: compiling is cheap, and gated as such — building a fifty-field record from its Python spelling is one of the shapes scripts/perf_gate.py --binding-build holds to an instruction count, and scripts/perf_budget.json owns the figure. repr(validator) gives an expression that rebuilds the schema, except for the forms the API reference lists, and the refusal says so. A required record key whose name ends in ?, which the dict literal cannot spell because every trailing ? there marks the key optional (schema language), prints marked, <required: 'a?'>, and its repr is a syntax error where it is read. One form rebuilds quietly: a class met with a declaration it did not make, which prints as the class's name and rebuilds as the class with its own. A schema carrying any of them is a schema to send as itself rather than as its repr.

import pickle

from valgebra import Validator

raised = False
try:
    pickle.dumps(Validator(int))
except TypeError as error:
    raised = True
    assert "cannot be pickled" in str(error)
assert raised

A ValidationError does pickle, because a failure has to be able to cross a process boundary back to whatever started the work.

It holds what its schema names, and lets go of it

A schema names classes, enum members and callables, and a validator keeps a reference to each: the walk reads them, so they must not be collected underneath it. That makes the natural spelling a reference cycle — a class that keeps its own validator holds the validator, and the validator holds the class — and the validator takes part in the cycle collector so the pair is freed like any other.

import gc
import sys
import weakref

from valgebra import Validator


class Model:
    a: int


Model.validator = Validator(Model)
watch = weakref.ref(Model)
del Model
gc.collect()
if sys.implementation.name == "cpython":
    assert watch() is None

The pair is freed on CPython. PyPy keeps alive every class an extension module is shown, valgebra's or any other's, so there the class outlives its last reference whether a validator holds it or not; PyPy on the installation page says what that costs a long-running process.

A validator can also be weakly referenced, so a registry keyed by schema can be a WeakValueDictionary and let its entries go.

It loads in the main interpreter of a process, once

A schema's forms are read by identity: Annotated, Literal, Any, a dataclass's fields and the markers of annotated_types are the objects the first build found in typing and the rest, kept for the life of the process. A subinterpreter holds its own copies of those modules, whose forms the kept ones are not, so a schema it built would mean something else: a pattern dropped, Any refusing every value. So import valgebra raises ImportError in any interpreter but the main one, whichever imports first, and in an interpreter an embedder starts again after Py_FinalizeEx, which would read what the first one freed. Importing it again in the interpreter that loaded it -- a reload, a cleared sys.modules -- works.

Under mod_wsgi, whose application groups are subinterpreters by default, run the application in the main interpreter with WSGIApplicationGroup %{GLOBAL}, as other extension modules ask. An isolated subinterpreter, such as one from concurrent.interpreters, refuses the module on its own: it declares no support for one.

It does not enforce ordering between separate checks

Two validators are two questions. A constraint that relates two values — this field is greater than that one, this id exists in that table — is not a set of values in the algebra's sense unless the relation is written inside one schema, where a predicate can see both. Cross-value invariants belong in the code that holds both values.

What follows from all of this

The boundaries are what buys the guarantees. Because nothing converts, an accept says something about the object you hold rather than about a copy. Because the algebra is closed, union, intersection and complement of schemas are schemas, and the relations between them are decidable on a published fragment. Both would go if the library grew the abilities above.