Skip to content

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:

pip install valgebra
# or
uv add valgebra

valgebra has no runtime dependencies. The examples in these pages import packages it does not:

Install them to run the examples as printed:

pip install annotated-types typing-extensions pytest fastapi pydantic numpy

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 spawn or forkserver method.
  • 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.