Installation¶
valgebra publishes prebuilt wheels to PyPI, so the common path needs no Rust toolchain. Building from source is the fallback for development or an unsupported platform; it is a Rust extension built with maturin, which requires a Rust toolchain.
From PyPI¶
With Python 3.11 or newer:
valgebra has no runtime dependencies. The examples in these pages import packages it does not:
- annotated-types, whose markers most refinement examples are written with. valgebra reads the markers structurally, never by importing that package.
- typing-extensions, for the
forms an example spells from it where an older Python's
typinglacks them. - pytest, which the examples showing a refusal use.
- FastAPI and pydantic, which the FastAPI recipe uses.
- numpy, which the arrays section of the boundaries page uses.
Install them to run the examples as printed:
Wheels are published for every supported CPython, 3.11 through 3.15, on Linux (manylinux and musllinux, x86_64 and aarch64), macOS (Intel and Apple silicon) and Windows x64, and from 3.12 on Windows arm64. Free-threaded CPython 3.14 and 3.15 have wheels on manylinux, musllinux, macOS and Windows x64, and PyPy 3.11 and 3.12 on manylinux. Free-threaded support starts at 3.14t; the earlier 3.13 free-threaded build is not a target.
From source¶
Building from source additionally requires:
- A stable Rust toolchain (edition 2024, MSRV 1.88) via rustup.
- uv (recommended) for the environment and the build.
git clone https://github.com/ppigazzini/valgebra && cd valgebra
uv sync # create .venv and install the dev dependencies
uv run --no-sync maturin develop --uv # build the Rust extension into the venv
Verify it works¶
import valgebra
from valgebra import Validator
print(valgebra.__version__)
assert Validator(int).is_valid(7)
PyPy¶
PyPy 8.0 is the target, on Python 3.11 and 3.12 and on Linux. A wheel is published
for each on manylinux x86_64 and aarch64, tagged pp80, and an installer matches
that tag exactly. So PyPy 7.3, and PyPy on musl, macOS or Windows, install from the
source distribution, which needs a Rust toolchain, and no lane here runs them. Every
push builds the extension against both series, imports it, and runs the product
suite there, with the repository checks whose answer is the interpreter's. Both
halves
are needed, because the C API PyPy offers is not CPython's: an extension there
runs through cpyext, which carries the limited API and not every static type
object CPython exports, so naming one of those links fine and fails at import
— and cpyext also answers differently, which no import can show. The PyPy
wheels are plain release builds, where the glibc Linux, macOS and Windows x64
CPython wheels are profile-guided:
a profiled extension runs out of the native stack budget cpyext sizes from
the recursion limit before the walk reaches its own depth bound, and the
process dies where the plain build reports the bound. The release runs the
product suite on every wheel set it ships, on each set's floor, newest and
free-threaded interpreters, and imports and checks the releases between -- the
smoke and smoke-musl matrices in .github/workflows/release.yml name them --
and each PyPy wheel on its own series, not only on the one the push lane builds.
The musllinux sets run in Alpine containers, the free-threaded wheels on uv's musl
build of each release, since the Docker library publishes no free-threaded image
(docs/dev/releasing.md in the repository).
One promise What it cannot do
makes holds differently there. A validator releases the
classes, enums and predicates its schema names when nothing else holds them, and
on PyPy it cannot: cpyext builds a PyTypeObject proxy for every class an
extension is shown and never frees it, so a class is kept alive from the first
validator that reads it, whatever that validator does afterwards. A long-running
process that compiles a schema over a throwaway class per request grows there
and does not on CPython. Nothing in valgebra can change this, and the suite's
four lifetime cases say so on PyPy rather than claiming to pass.
And one call CPython refuses, PyPy answers. object.__new__(Validator) makes a
validator whose schema was never compiled, which on PyPy 8.0 admits every
value. CPython's object.__new__ refuses a class with a constructor of its
own; PyPy's does not ask, and no code of valgebra's runs to refuse it. Build a
validator by calling Validator.
And one kind of value no extension can be shown there. cpyext hands an
extension an object by attaching it, and attaching an instance of a dict,
tuple or bytes subclass calls the subclass's own __len__. Where that
raises, nothing valgebra reads survives it: passed as the value itself, the
object raises the subclass's exception from validate or is_valid; held in a
list, a dict, a set or a record's field, it ends the process where the walk
reads it, or, in a list whose items the walk does not read (list[object]),
raises SystemError. CPython reads the storage and asks the type nothing, so
there each such value is checked by what it holds.
And one relation decides less there. A type defined in C, such as complex,
lays down an instance layout no class can combine with int's, and on CPython
valgebra reads it off the size of the type's instance:
intersection(complex, int).is_empty() is True. PyPy refuses the same
classes but names no size, so there that meet is not called empty, and
Validator(complex).relation_to(complement(int)) is undecided.
Free-threaded CPython¶
On a free-threaded interpreter a validator is immutable and shares no mutable
walk state, so object validation runs in parallel with the interpreter lock
disabled. The JSON path takes one lock: its string parser takes an
interned-string cache from a pool behind a lock and puts it back after the
parse, so concurrent validate_json/load calls contend only on that hand-off,
and neither the parse nor the walk holds it.
Three things read differently there:
- Threads checking one shared value contend for it. The walk takes each container's own lock to read an element, so threads validating one shared container serialize on it, where threads each holding their own copy run in parallel. Give each thread its own value, or check a shared value once.
- Forking a process whose threads are inside a walk can hang the child. A
child forked while other threads walk a shared container can inherit that
container's lock held, and wait on it for good; the interpreters with a lock
take no per-container lock. CPython warns against forking a threaded process
in any case; start worker processes with the
spawnorforkservermethod. - A record's field names are interned for good. A validator interns the names of the fields it reads, which is what makes a field lookup one pointer comparison, and the free-threaded build makes an interned string immortal: a process that builds a validator per request over field names it has not seen keeps every one of them. The builds with a lock free them with the last validator that held them.