API reference¶

The full public surface of the valgebra package. Every name is re-exported from the top-level valgebra namespace.

Compiling and checking¶

Validator ¶

A compiled, immutable schema validator.

Build one by calling Validator(schema), or with a combinator such as union, intersection, or recursive. Then check values with validate, is_valid, or ensure, and JSON documents with validate_json or is_valid_json.

Validation is a membership test against the set the schema denotes: the value is never copied or coerced. A validator never changes after it is built and is safe to share across threads. Its repr is the annotation that produces it, and it can be copied with copy.copy/copy.deepcopy.

close `method descriptor` ¶

close() -> Validator

Close every record in the schema: only declared keys are admitted throughout. The inverse of open.

Returns a new validator; this one is unchanged.

Returns:

Type	Description
`Validator`	A validator whose every record admits only its declared keys.

ensure `method descriptor` ¶

ensure(obj: object) -> object

Validate obj and return it unchanged.

The value-returning check. Because validation is a membership test rather than a coercion, the returned object is exactly the input; ensure exists so code that wants the checked value back reads distinctly from the boolean is_valid.

Parameters:

Name	Type	Description	Default
`obj`	`object`	The object to check.	required

Returns:

Type	Description
`object`	`obj` unchanged.

Raises:

Type	Description
`ValidationError`	If `obj` is not a member of the schema's set.

is_empty `method descriptor` ¶

is_empty() -> bool

Whether the schema is unsatisfiable — provably empty, so is_valid returns False for every value.

Decided soundly: True only when no value can belong to the schema — an unsatisfiable intersection, a fixed sequence with an impossible position, a record with an impossible required field, a refinement whose bounds cannot hold together (a lower bound above an upper bound, or a minimum length above a maximum), or a recursive schema with no base case (a mandatory self-reference that can never bottom out). It never reports a satisfiable schema as empty; for forms it cannot decide it returns False. The decision is also bounded by a fixed work budget, so on a deeply nested adversarial schema a False can mean "not proven empty within the bound" rather than "non-empty"; a real schema decides far inside the bound.

Returns:

Type	Description
`bool`	`True` if the schema denotes the empty set, else `False`.

is_equivalent `method descriptor` ¶

is_equivalent(other: object) -> bool

Whether this schema and other denote the same set — mutual inclusion.

other is any schema spec or compiled validator. Sound, like is_subtype_of: True only when the two are provably equivalent, whatever their syntax (bool | int is equivalent to int). Bounded by the same work budget as is_subtype_of, so on a deeply nested adversarial schema a False can mean "not proven equivalent within the bound".

Parameters:

Name	Type	Description	Default
`other`	`object`	The schema to compare, as a spec or validator.	required

Returns:

Type	Description
`bool`	`True` if the two schemas are equivalent, else `False`.

is_subtype_of `method descriptor` ¶

is_subtype_of(other: object) -> bool

Whether every value of this schema is also a value of other — set inclusion, the subtyping relation.

other is any schema spec or compiled validator. The decision is sound: True only when the inclusion provably holds (bool is a subtype of int, list[bool] of list[int], a recursive schema of a wider one, a class of a base class). For the forms it cannot decide — an alternation of sequence shapes, or a leaf relation the oracle declines — it returns False rather than a relation it cannot justify. The decision is bounded by a fixed work budget, so on a deeply nested adversarial schema a False can mean "not proven a subtype within the bound"; a real schema decides far inside the bound.

Parameters:

Name	Type	Description	Default
`other`	`object`	The candidate supertype, as a schema spec or validator.	required

Returns:

Type	Description
`bool`	`True` if this schema is a subtype of `other`, else `False`.

is_valid `method descriptor` ¶

is_valid(obj: object) -> bool

Whether obj is a member of the schema's set.

Check-only: it does not build an error and returns as soon as membership is decided. It raises only if a comparison the membership test performs raises a fatal interpreter signal (for example a KeyboardInterrupt during a long check); an ordinary exception in a comparison is folded to a non-member, as the membership contract requires.

Parameters:

Name	Type	Description	Default
`obj`	`object`	The object to check.	required

Returns:

Type	Description
`bool`	`True` if `obj` is a member of the schema's set, else `False`.

Raises:

Type	Description
`BaseException`	If a membership comparison raises a fatal interpreter signal, it propagates rather than being read as a non-member.

is_valid_json `method descriptor` ¶

is_valid_json(data: str | bytes) -> bool

Whether a JSON document parses and is a member of the schema's set.

Check-only: malformed or undecodable JSON, or input that is neither str nor bytes, is simply not a member and returns False. The raising entries (validate_json/load) report the same undecodable input as a structured json_invalid error. The document is validated in place against the parsed value, with no intermediate Python objects for the structure it walks. It raises only if a membership comparison raises a fatal interpreter signal.

Parameters:

Name	Type	Description	Default
`data`	`str \| bytes`	The JSON document, as `str` or `bytes`.	required

Returns:

Type	Description
`bool`	`True` if `data` parses and is a member of the schema's set, else
`bool`	`False`.

Raises:

Type	Description
`BaseException`	If a membership comparison raises a fatal interpreter signal, it propagates rather than being read as a non-member.

load `method descriptor` ¶

load(
    data: str | bytes, *, fail_fast: bool = False
) -> object

Validate a JSON document and return the parsed value.

Like validate_json, but returns the parsed Python object instead of discarding it, so a caller that needs the data does not parse it again. Parsing runs in Rust (jiter), and the parsed value is validated by the same walk, reaching the same decision and errors as validate.

Parameters:

Name	Type	Description	Default
`data`	`str \| bytes`	The JSON document, as `str` or `bytes`.	required
`fail_fast`	`bool`	Stop at the first failure instead of aggregating.	`False`

Returns:

Type	Description
`object`	The parsed Python object, once it is confirmed a member of the set.

Raises:

Type	Description
`ValidationError`	If the document is malformed or undecodable JSON (code `json_invalid`) or is not a member of the schema's set.
`TypeError`	If `data` is not `str` or `bytes`.

open `method descriptor` ¶

open() -> Validator

Open every record in the schema: undeclared keys are admitted throughout.

Returns a new validator; this one is unchanged.

Returns:

Type	Description
`Validator`	A validator whose every record admits keys beyond those declared.

simplify `method descriptor` ¶

simplify() -> Validator

An equivalent validator reduced by the lattice laws.

The result admits exactly the same values in a simpler form (flattened and deduplicated unions and intersections, identities applied, complements in negation-normal form). Returns a new validator; this one is unchanged.

Returns:

Type	Description
`Validator`	A validator denoting the same set in negation-normal form.

validate `method descriptor` ¶

validate(obj: object, *, fail_fast: bool = False) -> None

Validate obj, raising ValidationError if it is not a member of the schema's set. Check-only: obj is never copied or coerced.

Parameters:

Name	Type	Description	Default
`obj`	`object`	The object to check.	required
`fail_fast`	`bool`	Stop at the first failure instead of aggregating every independent failure into the error.	`False`

Returns:

Type	Description
`None`	`None` if `obj` is a member of the schema's set.

Raises:

Type	Description
`ValidationError`	If `obj` is not a member; its `errors` lists each failure with a code and a path.

validate_json `method descriptor` ¶

validate_json(
    data: str | bytes, *, fail_fast: bool = False
) -> None

Validate a JSON document, parsing it on the Rust path.

Parsing runs in Rust, faster than the standard library, and the parsed value runs the same validation walk as a native object, so this reaches the same decision and the same errors as validate on the parsed object. fail_fast behaves as it does for validate.

Parameters:

Name	Type	Description	Default
`data`	`str \| bytes`	The JSON document, as `str` or `bytes`.	required
`fail_fast`	`bool`	Stop at the first failure instead of aggregating.	`False`

Returns:

Type	Description
`None`	`None` if the document parses and is a member of the schema's set.

Raises:

Type	Description
`ValidationError`	If the document is malformed or undecodable JSON (code `json_invalid`) or is not a member of the schema's set.
`TypeError`	If `data` is not `str` or `bytes`.

Combinators¶

union `builtin` ¶

union(*schemas: object) -> Validator

The union of the given schemas: a value in at least one of their sets.

intersection `builtin` ¶

intersection(*schemas: object) -> Validator

The intersection of the given schemas: a value in every one of their sets.

complement `builtin` ¶

complement(schema: object) -> Validator

The complement of a schema: every value not in its set.

The whole-schema transforms simplify (reduce by the lattice laws), open, and close (a record's key set) are methods on the compiled validator (Validator.simplify/open/close), documented above. A fixed-length list is the native [A, B] literal (see the schema language).

Regex ¶

Annotated metadata: a string fully matches this regular expression.

Use as Annotated[str, Regex(r"[0-9a-f]{24}")]. The match is anchored — the whole string must match, as re.fullmatch does — and runs natively on the Rust path (a linear-time engine), so a pattern check stays on the validation fast path rather than crossing into Python like a predicate. A bare re.Pattern (from re.compile) is accepted as metadata too.

Recursion¶

recursive `builtin` ¶

recursive(
    builder: Callable[[Validator], object],
) -> Validator

Build a recursive schema as a checked fixpoint.

builder receives a placeholder validator standing for the schema being defined and returns its body. The placeholder's self-reference is resolved to a back edge, and a non-contractive body — one whose recursive reference is not under a structural constructor — is rejected.

Lattice bounds¶

anything `module-attribute` ¶

anything: Validator = anything

A compiled, immutable schema validator.

Build one by calling Validator(schema), or with a combinator such as union, intersection, or recursive. Then check values with validate, is_valid, or ensure, and JSON documents with validate_json or is_valid_json.

Validation is a membership test against the set the schema denotes: the value is never copied or coerced. A validator never changes after it is built and is safe to share across threads. Its repr is the annotation that produces it, and it can be copied with copy.copy/copy.deepcopy.

nothing `module-attribute` ¶

nothing: Validator = nothing

A compiled, immutable schema validator.

Build one by calling Validator(schema), or with a combinator such as union, intersection, or recursive. Then check values with validate, is_valid, or ensure, and JSON documents with validate_json or is_valid_json.

Validation is a membership test against the set the schema denotes: the value is never copied or coerced. A validator never changes after it is built and is safe to share across threads. Its repr is the annotation that produces it, and it can be copied with copy.copy/copy.deepcopy.

Errors¶

ValidationError ¶

Bases: Exception

Package version¶

valgebra.__version__ is the installed distribution version as a string. It is read from the package metadata maturin derives from the Cargo workspace manifest, so it always matches the built wheel and never drifts from a hand-maintained literal.

import valgebra

print(valgebra.__version__)

API reference¶

Compiling and checking¶

Validator ¶

close method descriptor ¶

ensure method descriptor ¶

is_empty method descriptor ¶

is_equivalent method descriptor ¶

is_subtype_of method descriptor ¶

is_valid method descriptor ¶

is_valid_json method descriptor ¶

load method descriptor ¶

open method descriptor ¶

simplify method descriptor ¶

validate method descriptor ¶

validate_json method descriptor ¶

Combinators¶

union builtin ¶

intersection builtin ¶

complement builtin ¶

Refinement markers¶

Regex ¶

Recursion¶

recursive builtin ¶

Lattice bounds¶

anything module-attribute ¶

nothing module-attribute ¶

Errors¶

ValidationError ¶

Package version¶

close `method descriptor` ¶

ensure `method descriptor` ¶

is_empty `method descriptor` ¶

is_equivalent `method descriptor` ¶

is_subtype_of `method descriptor` ¶

is_valid `method descriptor` ¶

is_valid_json `method descriptor` ¶

load `method descriptor` ¶

open `method descriptor` ¶

simplify `method descriptor` ¶

validate `method descriptor` ¶

validate_json `method descriptor` ¶

union `builtin` ¶

intersection `builtin` ¶

complement `builtin` ¶

recursive `builtin` ¶

anything `module-attribute` ¶

nothing `module-attribute` ¶