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, notuple, 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_toanswers"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 withis_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.