Versioning, and what counts as a break¶
The version follows Semantic Versioning,
and while the line is 0.x the minor number is the breaking one: 0.1.0 to
0.2.0 may break, 0.1.0 to 0.1.1 may not. Below 0.1.0 there is no minor
number to carry a break, so every 0.0.x release may break, and its notes say
where. The line stays on 0.0.x for a long time, so a break does not wait for
0.1.0: it ships in a 0.0.x release, after the warning below.
What a break means here is specific, because a validator has two surfaces and only one of them is the API:
- A break. A value that validated and no longer does, or a value that did
not and now does. An error
codeor a violationpaththat changes for a failure that was already reported. A name removed or renamed, a parameter that stops accepting what it accepted, an exception type that changes. - Not a break. A relation that answered
False("not proven") and now answersTrue. The conservative answer is documented as "no, or not proven" (decidability) -- so code that treatsFalseas a proof of the negative was reading a guarantee that was never given. Widenings are listed in the notes below, and they are the commonest entry. - Not a break, and worth reading anyway. A
reprthat changes, anexpectedstring reworded, a message improved. They are described in the notes because tests pin them, and pinning one is a choice to be told.
Deprecation¶
A name on its way out keeps working, and warns, for at least three
releases: calling it emits a DeprecationWarning naming what replaces it, and
the notes below carry an entry saying it is going. A later release removes it,
and its notes say so.
Nothing is removed without that window, and nothing that warns is left warning indefinitely -- a warning that never resolves is a cost with no end, and a removal with no warning is a break a reader had no way to see coming.
Changelog¶
All notable changes to valgebra are recorded here. The format follows Keep a Changelog, and the project follows Semantic Versioning.
Unreleased¶
Added¶
-
A pattern's word lengths decide a length bound. The least and the most length of the strings a
Regexmatches are read off its automaton, so a pattern on astris below aMaxLenor aMinLenits strings keep to and outside one a string breaks, at every bound:Annotated[str, Regex("[a-f0-9]{24}")]issubsetofAnnotated[str, MaxLen(n)]for everynfrom 24, andAnnotated[str, Regex(".*-x")]not_subsetof everyMaxLen, where each stayedundecidedpast a few hundred characters, the bound's own automaton no longer fitting its states. A bound a pattern keeps to changes no string of it, so the meet of the two is the pattern, below the same patterns the pattern alone is below. Against 0.0.31's recording no decision is lost and none is slower. -
A union's branch that is a meet of atoms is one clause. A meet the rules decline is distributed across its unions where its normal form spans four clauses at most, and a union whose branch was a meet counted past any bound, so such a meet was never distributed. A branch that is a meet holding no union and no meet is the one clause its members join, so
w implies w and tspelledunion(intersection(has("w"), has("w", "t")), complement(has("w")))reads as its flat spelling does: met with a record whose field holds a predicate, which keeps the record from the set representation, it isnot_subsetofnothing, where it stayedundecided. -
A meet holding a union is asked as its clauses once all else declines. A relation every asking leaves undecided whose subject is a meet holding a union is asked once more, a budget of its own, with each meet holding a union read as the union of its clauses, one union at a time: below a supertype where every clause is, and outside it where one clause is.
Z & (X | Y)is related as(Z & X) | (Z & Y)is, so aoneOfof two pairs a translation from JSON Schema writes,{"oneOf": [{a: 1, b: 1}, {a: 2, b: 2}]}besiderequired: ["a", "b"], issubsetofif a = 1 then b = 1 else b = 2, and a meet subject below a meet supertype where it is below each member, where each stayedundecided. The asking before it is unchanged, so no answer it gives moves; against 0.0.31's recording no decision is lost and none is slower.
0.0.31 - 2026-11-21¶
A release of answers and speed, with no node. Where the deciders declined, a pair is now refuted on
a value guessed from its subject or aimed outside its supertype, a meet reads a complement pushed
in, a branch in its clause, a guard beside a member of its kind and a meet among a key's types,
records met over a guarded fixpoint are related as one record, and a length bound beside a record
leaves the record it counts. Over the 70,000 pairs each generation of a fuzzer draws, the relations
give 1,570 answers more than 0.0.30 on the first generation, 3,491 on the second and 2,923 on the
fourth, and lose none, and no call is ten times slower past 50 ms; the families of exact relations
over lists, records, mappings, TypedDicts and recursions give 19,269 more and lose none. Read
through valgebra-jsonschema, the JSON Schema test suite and corpus studies move no count, and the
containment study decides 65 questions more, 64 refutations and a proof: of the 36 refutations
against the suite's labels, the 35 in draft 4 stand on a const, which draft 4 does not have, and
the one in 2020-12 on {"bar": {"baz": {}}}, which jsonschema and jsonschema-rs both admit in a
subject the suite labels unsatisfiable. valgebra-vtjson's differential suite passes.
Against 0.0.30 built here from its tag, on CPython 3.11 through 3.15, a list of floats under order
bounds counts 42.5% to 49.4% fewer instructions on the profiled wheels, a list of strings under a
pattern 15.0% to 16.6% fewer and a record of refined fields 0.7% to 1.0% fewer, and a relation
between two dataclasses reads 40.8% fewer on 3.15 and 3.12. Every other shape counts within 0.5% of
0.0.30's but seven, each of which reads the same in an environment 4,096 bytes larger: on 3.13 a
JSON document's integers, union and refusal 2.0% to 4.3% more, the copy a realloc makes as the
parser grows the document's array from empty; on 3.15 a deep JSON document 1.41% and a list's
explanation 0.54% more; on 3.11 a union's build 0.99%, a scalar's explanation 0.76% and a dataclass
0.55% more, in glibc's allocator. The instruction gate's ten decision workloads count within 0.2% of
0.0.30's.
Added¶
- A pair the deciders decline is refuted on a value guessed from the subject. Where neither
the rules nor the set representation decides a relation and the subject denotes more values
than the finite reading builds, the relation guesses up to 64 small values from the subject's
spelling -- a value of each scalar kind it names, each of its constants, the sequences, sets and
dicts its items and fields guess, three containers deep, and a reference read through its
definition -- and walks each through both schemas. A
value the subject admits and the other schema refuses refutes the pair: the JSON fixpoint is
not_subsetof~list | list[~list | Annotated[list[Any], MaxLen(1)]]on[[None, False]], a fixpoint overtuple[complement(t), t]of its swap on(None, 1), anddict[float, int]ofdict[Literal[1.0], int]on{0.5: 0}, where each stayedundecided. The guesses prove nothing, so an inclusion is never decided by them. Over 4,000 pairs of recursive schemas drawn over eleven leaves, 36 of the 62 relations 0.0.30 left undecided are refuted, and no answer it gave moves. On the containment suite of Attouche et al. read throughvalgebra-jsonschema, 8 more questions are refuted, 5 against the suite's labels: four where draft 4's missingconstleaves the subject every value, and one 2020-12 pair labeled empty whose refuting value{"bar": {"baz": {}}}jsonschemaandjsonschema-rsboth admit.
The readings that walk a value -- this one and the finite reading's -- read a bound or a step only
where its operand is an exact int, bool or float, or the standard library's Fraction or
Decimal: a class of the program's own compares by its code, which a second call may answer
anew.
-
A pair is refuted on a value aimed outside the supertype. Beside the values it guesses from the subject's spelling, the relation builds values aimed outside the supertype, its negation pushed one constructor in as a witness generator for JSON Schema pushes it through each operator (Attouche et al., Witness Generation for JSON Schema, PVLDB 2022, §5.2): outside a list of
X, a list holding one value outsideX; outside a sequence no item may follow, one item more; outside a record, a dict lacking a required key, holding a field outside its type, or holding a key the record closes out; outside a bound, a number beside it; outside a constant, the integer or the string beside it; outside a complement, its operand's members; and one value of each other kind. A complement in the subject is guessed the same way. Each is walked through both schemas, so a value wide of the difference refutes nothing, and the relation still walks at most 64 values. The JSON value fixpoint isnot_subsetof JSON Schema'sdependenciesas a translation spells it, on{"bar": None}. On the containment suite of Attouche et al. read throughvalgebra-jsonschema, 41 more draft-4 questions are refuted, 23 against the suite's labels; in each of thoseconst, which draft 4 does not have, leaves the subject every value, andjsonschemaandjsonschema-rsplace the refuting value inside it and outside the supertype. Of the 28 undecided questions the suite labels refutations, 17 remain, each against a supertype the companion spells with a predicate, whose code the reading does not run. -
Records met over a guarded fixpoint are related as one record. Two records met are their field-by-field meet, and a field's meet is now decided where a reference stands in it: a field one record guards to its kind over the JSON values,
([T] | ~list) & json, met with[str], is below[T], since a list of strings is no value of~list. That is the field a translation from JSON Schema writes for anallOfmember narrowing an array's items, and{"tags": [str]}met with{"tags?": ([Literal["a"]] | ~list) & json}issubsetof{"tags": [Literal["a"]]}, where it wasundecided. A goal the rules decline is read by the set representation where it holds a reference and a meet, a union or a complement tops one side; one a constructor or a reference tops on both sides is left to the rules, which take it apart. Against 0.0.30's recording, two more decisions are made, none is lost and none is slower. On the containment suite read throughvalgebra-jsonschema, 15 more draft-4 questions overuniqueItemsare refuted, 8 against the suite's labels: in eachconst, which draft 4 does not have, leaves the subject every value, andjsonschemaandjsonschema-rsadmit[1]there and refuse it in the supertype. -
A guard beside a member of its kind is dropped from a meet. The complement of a container of anything --
~list[Any],~dict[Any, Any]and the like -- holds no value of the container's kind, so beside a member of that kind alone it is dropped from its union, the meet being the same set:list[str] & ([T] | ~list)is read aslist[str] & [T], and{"a": int} & (R | ~dict)as the record met withR. That is the guard a translation from JSON Schema writes for a keyword of one kind, beside the object or array it spells as a record or a list, and the formvalgebra-jsonschemacompiles anallOfmember narrowing an array field's items to,{"tags": [str], str: json} & ({"tags?": ([T] | ~list) & json, str: json} | ~dict) & json, issubsetof{"tags": [T]}.open(), where it wasundecided. A branch that is no such guard is not dropped by its kinds. On the containment suite read throughvalgebra-jsonschema, one more 2020-12 question is proven, as the suite labels it; against 0.0.30's recording no decision is lost and none is slower. -
A meet reads a complement among its members pushed in, and a union's branch in its clause. Where a meet is related to a supertype, a member that is the complement of a union is read as its branches' complements, and one that is the complement of a meet all of whose conjuncts but one are members as that conjunct's complement, where that narrows the meet. A union's branch that is a meet is read beside the members its clause holds: dropped where one of its conjuncts shares no value with them, its own unions narrowed the same way. And the complement of a reference shares no value with a member its definition holds as a branch. Each reading leaves the same set. They are the shapes a translation from JSON Schema writes beside an object --
not Xas~X & J,Jthe JSON values,if I then Tas(~I & J) | (I & T & J), andanyOfandoneOfas unions of meets each holdingJ, every keyword guarded to its kind -- so the object anot not,not anyOf,if/thenoranyOfrequireskof issubsetof{"k": anything, str: anything}, where each wasundecided, and so is one aoneOfrequires it of whose one branch excludes a key the other requires. A meet read for its emptiness takes neither reading, since its narrowed meet is asked before the distribution of the meet as written. On the containment suite and the corpus read throughvalgebra-jsonschemano answer moves, and against 0.0.30's recording no decision is lost and none is slower. -
A length bound beside a record leaves the record it counts. A record under a length bound that counts its names is read as the record those leave: a least length counting every name of a closed record requires each, and a greatest length counting its required names admits no other key, so
Annotated[{"a?": int}, MinLen(1)]issubsetof{"a": int}. A bound over every dict met with records reads the one record they meet into the same way, and one mapping keyed by words beside it goes to the count of its words:dict[Literal["k"], Any] & Annotated[dict[str, Any], MinLen(1)]issubsetof{"k": anything, str: anything}, where it wasundecided. That is how a translation from JSON Schema writesminPropertiesandmaxPropertiesbeside an object, andpropertyNamesspelled as the closed record of its names, so presence through aminPropertiescounting an object's every possible name, and absence through amaxPropertiescounting its required ones, is decided. A bound counting fewer names proves nothing of any one of them; the relation takes only proofs through the record, and a refined record's emptiness is read off it. On the containment suite and the corpus read throughvalgebra-jsonschemano answer moves, and against 0.0.30's recording no decision is lost and none is slower. -
A meet among a key's types is read beside the key's other types. Records met hold no value where a key one of them requires has types meeting in nothing, and a type that is itself a meet is now spliced into that meet, so a field one record guards to its kind,
([T] | ~list) & json, is read in its clause beside the others.{"tags": [str]}met with{"tags?": ([Literal["a"]] | ~list) & json}and a record requiring a list of at least one"c"is empty, where it wasundecided: the tags are strings,"a"and"c"at once. On the containment suite and the corpus read throughvalgebra-jsonschemano answer moves, and against 0.0.30's recording no decision is lost and none is slower. -
How it works. The explanation opens with a page that follows one schema from its annotation to both answers: the frontend and the normal form, the walk that answers membership in one call into Rust over the object held, and the deciders that answer inclusion with
subset,not_subsetorundecided; where valgebra sits beside a parser, a static checker and its two companions; and what it does not cover. Each step has a diagram, amermaidblock the site draws in its own palette, light or dark, and GitHub draws from the same text, and its examples run as written.
Changed¶
-
The documentation site is built by Zensical. Material for MkDocs, which reaches its end of life on 2027-05-05, gives way to Zensical, its maintained successor, which builds the site from the same
mkdocs.ymlunderzensical build --strict: its own search, the redirects from each page's former address, thellms.txtmanifest and thellms-full.txtexport, the Mermaid diagrams and the mkdocstrings API reference. No page moves. -
A relation keeps what it read of a class. A refutation about a class reads what a direct instance of it can carry off the namespaces of its
__mro__, and a class's own reading is now kept across relations and taken where the namespace still holds the same names, each read as the same member, so an assignment to the class between two relations is read as it stands. A refutation between two dataclasses reads 40.8% fewer instructions on CPython 3.15 and 3.12. The kept readings hold strings alone, so a class a program drops is freed as it would be. -
A predicate's stack check is one subtraction. On CPython before 3.14 the walk asks, before it calls a predicate, whether the thread's stack has room for the Python it runs, and that question now reads 7 instructions where it read 17: a thousand integers under a predicate read 5.0% fewer instructions on CPython 3.12.
-
A list of strings under one pattern reads the pattern once. A list whose element is a
strunder one pattern, alone or beside length bounds, finds the pattern's compiled program once for the list, where each element's check looked it up: two hundred strings under one pattern read 15.3% fewer instructions on the profiled CPython 3.12 wheel, and 15.0% fewer than 0.0.30's. -
A list of floats under order bounds is read as one interval. Where every constraint of a
floatelement is an order bound whose operand a float holds exactly, the bounds are read once for the list, each end open or closed, and an exactfloatis its two comparisons, where it went through the constraints' loop and read its operand at every element: a thousand floats under one bound read 43% to 49% fewer instructions on the profiled wheels of CPython 3.11 to 3.15 than 0.0.30's. A single float under such a bound is admitted where the constraint is read, with no call into the bound's own reading, which a refusal and every other value still take: a record of three refined fields reads 0.7% to 1% fewer. Every answer and every report is the one the comparisons give.
Fixed¶
-
Opening or closing a
recursiveplaceholder is refused.open()andclose()reach a fixpoint's records through the reference to its definition, and the placeholder a builder is handed names a definition not built until the builder returns. Both left the placeholder as it was, sorecursive(lambda t: union(None, {"k": Validator(t).open()}))was the fixpoint built without.open(), refusing{"k": {"k": None, "z": 1}}, which its body written out around it admits; a record holding the placeholder, opened or closed beside a record left as declared, built another set the same way. Both now raiseValueErroron a schema holding a placeholder, in its root or in a definition. A call that returned now raises: open the validatorrecursivereturns, or writeanything: anythinginto the record where it is declared. -
A walk on PyPy under a lowered recursion limit asks for room before its question can overflow. PyPy sizes the stack its C-API calls may use by the recursion limit, and the walk asks
__pypy__.stack_almost_fullfrom a frame kept free below it, once it has gone a step deeper than the last answer. With a 2 KiB step and a 16 KiB reserve that frame could land past PyPy's threshold, where the question itself overflowed insidecpyextand ended the process: explaining a list nested 1,600 deep or a JSON value twelve lists deep did so on PyPy 3.12 under limits of 38, 41 and 53, and on PyPy 3.11 under 37, 38, 40, 42 and 43. The walk asks every 1 KiB from 12 KiB below it, and under every limit from 37 to 120 no process ends on either; a value deep enough to cross a step reads up to 12% slower on PyPy. The limits page's floor is 37, where it was 45. -
A float meets a
Decimalbound as theDecimalit equals. Python compares a float with aDecimalexactly and through the thread'sDecimalcontext, whoseFloatOperationtrap makes the comparison raise, and the walk read the raise as a refusal: under the trapAnnotated[float, Ge(Decimal("0.25"))]refused0.75, reportinggreater_than_equalwith "expected >= Decimal('0.25'), got 0.75", while outside it admits0.75. The relations followed:Literal[0.75]wasnot_subsetof it under the trap andsubsetoutside. The walk, and the relations' ordering and reading of two bounds, compare the float asDecimal.from_floatmakes it, exact and silent under the trap, so every answer is the one Python's exact comparison gives outside it, whatever the context. pydantic 2.14 admits0.75under the trap too; msgspec refuses aDecimalbound. -
A predicate re-entering its validator raises
RecursionErroron CPython 3.12 and 3.13. A predicate that calls its own validator re-enters the walk with nothing between two calls that those interpreters check against the native stack: about 3 KiB a call beside one unit of a C-recursion limit of thousands, so the chain ended CPython 3.12.16 in a segmentation fault on every thread of 1 MiB or less under the default recursion limit, and on the main thread under a limit of 10,000. Before 3.14 the walk reads the thread's own stack bounds before it calls a predicate -- once a thread, through thestackercrate, as 3.14 reads them for its own check -- and with less than 32 KiB left raisesRecursionError("Stack overflow (N kB of the thread's stack left)")instead of calling it, which 3.14 and later raise at the Python frame between two calls. It costs about 20 instructions a predicate on 3.12 and nothing on 3.14 and later. Not on musl, whosepthread_getattr_npreports the main thread's stack mapped so far, and where 3.15.2's own check also lets the chain end the process on a 128 KiB thread, and not for an__eq__orisinstancehook that re-enters; a walk between two re-entries still needs the stack it uses, so deep values on a thread under 1 MiB keep the limits page's floor. A level refused on PyPy for PyPy's stack rather than the walk's bound is reported as "a value the thread's stack has room to walk" rather than as past the 384-level bound.
0.0.30 - 2026-11-19¶
A release of answers, with two additions and no node. A tuple or a record is read a component at a
time where the set of the whole is past the build's bounds: a string of 584 code points or more
beside a part only the set representation reads, such as the meet a translation writes for
{"type": "integer", "minimum": 0}, left the product undecided, and the product holds a value
where each part does and none where one part holds none. Over the 70,000 pairs each generation of a
fuzzer draws, the relations give 969 answers more than 0.0.29 on the second generation, 40 on the
first and 868 on the fourth, and lose none; the families of exact relations over lists, records,
mappings, TypedDicts and recursions give 5,738 more and lose none. The JSON Schema test suite,
corpus and containment studies, read through valgebra-jsonschema, move no count, and
valgebra-vtjson's differential suite passes.
Against 0.0.29 built here from its tag, on CPython 3.11 through 3.15, every shape of the profiled wheels counts within 0.5% of 0.0.29's but three on 3.15: the explaining walk of a record 4.70% more, of a list 0.93% more and a deep JSON document 0.56% fewer, each of which an environment 4,096 bytes larger reads alike, so the move is where the allocator's heap starts and not the code. The instruction gate's ten decision workloads count from 0.11% fewer instructions to 0.38% more.
Added¶
-
A meet or a complement only the sets read holds a value a refutation stands on.
tuple[Annotated[str, MaxLen(584)], M], forMthe meet a translation of{"type": "integer", "minimum": 0}writes, isnot_subsetofnothingby("", 0), and a record of the same two required fields isnot_subsetof{}, where both stayedundecided. A string of at most 584 code points is a table past the set representation's state bound, so the pair's set is refused whole, and the meet beside it is read alone, as a refinement is. A complement such as~Annotated[int, Ge(0)]beside the same string is read the same way. -
A product is read empty a component at a time.
tuple[Annotated[str, MaxLen(584)], E], forEa meet only the set representation proves empty, such asM & (Annotated[int, Lt(0)] | Annotated[float, Lt(0)]), issubsetofnothingand of every other validator, andis_emptyreads it empty, where both stayedundecided; so is a record with such a required field. The pair's own set is refused for its string, and the empty meet beside it is read alone.
0.0.29 - 2026-11-18¶
A release of the user guide's addresses, with no change to an answer, a message or a code: every membership, relation, error and render is the one 0.0.28 gave.
Changed¶
- The user guide's pages are named for their topics. A page's address is
its section of the site and its topic,
/guides/schema-language/where it was/03-schema-language/, the release notes at/changelog/and the API reference at/reference/api/. Every address the site has served answers still, with a page that sends the reader to the new one and keeps the anchor the link named where the browser runs scripts, so a link in the README of an earlier release keeps working.
0.0.28 - 2026-11-16¶
A release of speed, with no addition, no fix and no node. The walk reads the shapes a JSON Schema
translation writes by each value's type -- the JSON values, alone, as a list's element, as a
mapping's value and beside a keyword's guard; the numbers JSON Schema calls integer and number;
a string under length bounds; and a record whose undeclared keys hold the JSON values, read by its
keys -- where it walked each node of them, and composing two validators builds no copy of an operand
whose indices do not move. Every answer is the one 0.0.27 gave: against PyPI's 0.0.27 the
metamorphic gate moves no membership and loses or contradicts no decision. The one count a caller
can see move is a predicate's: validate explaining a refused record whose catch-all clause reads
values runs a predicate on a field before the refusal once, where it ran twice. The algebra page
states what == promises a decision: what one proves of a validator holds of every validator equal
to it, and two equal validators never answer contrary, though past a query's bound one may decline
where the other decides.
Changed¶
-
A tree of scalars is read by each value's type. A recursive definition whose union holds only scalar leaves refusing every list and dict, a list of the definition and a mapping of
strkeys to it -- the valuesjson.loadsreturns,int | list[t]-- asks each value's exact type once, where the walk spent a reference, its pair on the trail, the union's level and a branch per member around the same question. Outside the definition,list[J]anddict[str, J]--Jthe definition, which a JSON Schema translation meets every array and object with -- read each value the same way, the bounds asked once for the container. Where a meet remembers what it walked, as one oflist[J]and a list of records reachingJdoes, the scalars are read by type and the containers walked and kept. A value of no exact builtin type, one near either bound and one inside itself are walked as before, and a walk that explains reads the definition the general way. -
A leaf is decided by a value's type and its number. A union, meet or complement of scalar kinds and of refinements of
intandfloatby bounds and steps -- JSON Schema'sinteger,(int | Annotated[float, MultipleOf(1)]) & ~bool, andnumber-- is specialized to each exact builtin type when the validator is built, so a list of one, a mapping ofstrkeys to one and a JSON array of one read each element's type and, where the type leaves it open, its number. Afloatunder order bounds alone is two comparisons against the interval they admit. Anintpast a machine word the leaf reads, and a subclass, are walked. -
A leaf may hold the JSON values. A union, meet or complement of leaves beside a reference to a tree of scalars, such as
(~int | Annotated[int, Ge(0)]) & JwithJthe JSON values -- the guard a JSON Schema translation writes for a keyword with notypebeside it, and for everynot,ifandthen-- answers a scalar by the tree's leaves, and a list or a dict is walked as before. -
A list of strings under length bounds is read against one range.
list[Annotated[str, MinLen(m), MaxLen(n)]]folds its bounds into one range of code points, read once for the list, and compares each exactstr's length with it. A meet ofstrand its length refinements,str & Annotated[str, MaxLen(n)] & Annotated[str, MinLen(m)]as a JSON Schema translation writesminLengthbesidemaxLength, is the same range, whatever else the validator holds. -
A record whose catch-all clause reads values is read by its keys. A record that admits an undeclared key by its value,
{id: int, str: J}-- what a translation writes whereadditionalPropertiesis absent -- probes its declared fields as aTypedDictdoes, and scans the keys it does not declare alone. Whenvalidateexplains a refused value it resumes where the first pass stopped, so a predicate on a field before the refusal runs once where it ran twice (docs/guides/refinements.md). -
Composing a validator copies no operand whose indices do not move. The first operand of a combination, and one whose definitions the table holds at its start, enters as the handle it holds: a record nested sixty deep, each level met with the JSON values, composes in about half the time, and a relation between two built validators, which composes the two, counts 17% to 18% fewer instructions.
0.0.27 - 2026-11-14¶
A release of fixes, with no addition and no node. Five readings 0.0.26 answered wrong or paid too
much for are repaired: a question asked inside a recursive builder stops at its placeholder
rather than refusing the value, a subject of finitely many values is not refuted on a value the
walk stopped on, a subject of one long value is built in time linear in its items and past 4,096
not at all, an undecided relation over a recursive subject builds one copy of a body for each
definition, and two validators each below the other are equivalent. Over the 60,000 pairs each
generation of a fuzzer draws, the relations give 0.0.26's answers and lose none, with one
is_equivalent more on the second. Against PyPI's 0.0.26 the metamorphic gate moves no
membership and loses or contradicts no decision, and the companions' suites and studies read no
difference.
Against 0.0.26 built here from its tag, on CPython 3.15, the instruction gate's 44 workloads count from 0.07% fewer instructions to 0.16% more, and the profiled wheel's seven shapes count alike. On the profiled wheels of CPython 3.11 through 3.15 every shape counts within 0.7% of 0.0.26's but one: a relation between two built validators counts 2.6% to 3.1% fewer, the deciders and the reading by values sharing one oracle where 0.0.26 built a second for the reading. On the free-threaded 3.14 and 3.15 a shape of a few thousand instructions counts 3% to 46% apart from one build to another, either way, the count 0.0.26's section names as not repeating; the shapes past that count within 3%.
Read on the wheels PyPI serves, two environments of each release on each of CPython 3.11
through 3.15, on an AMD Ryzen 7 PRO 7840U under WSL2, every shape counts within 2% of 0.0.26's
instructions but one: a relation between two built validators counts 2.6% to 3.2% fewer, the one
oracle named above, and takes 6% to 10% less time on 3.11, 3.12, 3.13 and 3.15. Fifteen shapes
moved by 5% or more at the instructions 0.0.26's wheel counts, which is where each build placed
its loop, and none is charged to a change. Slower: on 3.15 list[bool] 31%, list[float] 19%,
list[str] 16% and list[int | str] 13%; on 3.12 list[int | None] 5%. Faster: on 3.15
list[None] 39%, ten thousand integers 26% and the list nested twenty-five deep 9% to 10%; on
3.13 list[None] and list[bool] 17% and a record 5% to 6%; on 3.12 list[None] 15%,
list[int | str] 9% to 10% and the JSON values' parsed document 8%; on 3.14 list[int | None]
6% to 7%.
Fixed¶
-
A question asked inside a
recursivebuilder proves nothing about its placeholder. The placeholder stands for a definition not built yet, and a walk that meets it stops withunresolved_recursionrather than refusing the value, so every decider that reads a walk declines there. Inside the builder ofrecursive(lambda t: union(int, [t])),Literal[1]wasnot_subsetoftandsubsetofcomplement(t), and the meet of a non-emptylist[Literal[1]]withlist[t]was proved empty, while the finished set holds1and[1]; each isundecidedor not proved.complement(t).is_valid(1)isFalsethere, since a stop refuses a value from a set and from its complement alike. -
A subject of finitely many values is not refuted on a value the walk stopped on. The relation read value by value took a walk that stopped at the depth bound as a refusal and answered
not_subset:1under twenty one-item tuples against a fixpoint whose body admits every such nesting, where each level spends a dozen meets of the walk's depth. Each value is asked in three answers, so the pair isundecided; a value refused still refutes. -
A subject of one long value is built in time linear in its items, and past 4,096 not at all. A sequence of one exact length,
list[Literal[1]]met withMinLen(n)andMaxLen(n), was built before its length was read:n = 2**62raised aPanicExceptionout ofrelation_to, whichexcept Exceptiondoes not catch, a length near3 * 10**17aborted the process, and10**5items took 18 s, each item copying the row before it. A value of more than 4,096 items or fields is left to the deciders before anything is built, and one within it is built an item at a time: 4,096 items are refuted in milliseconds. -
A relation the deciders leave undecided over a recursive subject keeps its memory. The subject unfolded twice copied its definition's body at every reference, so a body naming its definition
mtimes builtmcopies ofmcopies before the set representation refused it unread:prefixItemsof forty self-references againstuniqueItems, asvalgebra-jsonschemacompiles them, took 14.5 s and 1.6 GB on 0.0.26 and could abort the process under a memory limit, and a fixpoint of 32,768 keys against a predicate took 23 s. One copy of a body is built for each definition, unfoldings left and polarity, and every reference holds it, and two handles of one node compare equal without being read: 19 ms and 40 MB, and 12 ms, where 0.0.25 took 86 ms and 7 ms. Every answer is the one it was. -
Two validators are equivalent where each is below the other.
is_equivalentasked both directions on one budget with the rules and the sets alone, so it could answerFalsewhererelation_toproved"subset"both ways: an empty tuple of nested lists againsttuple[()], which the relation reads by its one value, and two translations from JSON Schema of the non-numbers, which a reading past the rules decides. It asks the two inclusionsrelation_toasks, each on a budget of its own.
0.0.26 - 2026-11-13¶
A release of answers, with eight additions and no node. Each reads a pair 0.0.25 left
undecided: a meet of sequences read as the one sequence of its items' meet, a set holding a
value refuted below a complement it lies inside, a declined pair split on a set its supertype
negates and each half asked of its parts, a subject of finitely many constants related by each
of its values, a recursive subject narrowed through two unfoldings, and an integer bound held
past 64 bits. Three fixes bound what a report builds over a long key or long text. Over the
60,000 pairs each generation of a fuzzer draws, the relations give 117 answers more than 0.0.25
on the second and 22 more on the first, and lose none. The JSON Schema containment suite, read
through valgebra-jsonschema, proves 200 more of its labeled inclusions and refutes 13 more,
with no proof against a label; each of the 11 more refutations against a label is a wrong label
the jsonschema package admits a witness against.
Against 0.0.25 built here from its tag, on CPython 3.15, the instruction gate's 44 workloads count from 0.07% fewer instructions to 0.35% more, each within its ceiling. On the profiled wheels of CPython 3.11 through 3.15 every shape counts within 0.5% of 0.0.25's but two. A relation between two built validators counts 3.7% to 4.2% more, 79 instructions a call on 3.15, for the relation by values a subject of finitely many constants gets where both deciders decline; the call's entry was read out of line and the count did not move, the profiled build placing the decider apart. The explaining walk of a scalar counts 0.4% to 0.5% more, 1.4% on 3.11, where a summary renders long text from its head and a report shares a key's string across its failures. The JSON shapes that count otherwise do so at one size of the environment and not at the other, which is an allocator's, but a union of records on 3.13, which counts 2.2% fewer at both. On the free-threaded 3.14 and 3.15 a count of a shape of a few thousand instructions does not repeat from one build to another: two builds whose walks count alike on every interpreter with the GIL read different shapes higher in each of three counts, the explaining walk of a scalar by 0.6% to 3.0% in one and a literal by 11% to 49% in the other.
Read on the wheels PyPI serves, two environments of each release on each of CPython 3.11
through 3.15, on an AMD Ryzen 7 PRO 7840U under WSL2, every shape counts within 2% of 0.0.25's
instructions but one: a relation between two built validators counts 3.7% to 3.9% more, the
relation by values named above, and takes 5% to 10% more time on each interpreter. A JSON document
refused by list[int] counts 5.2% more on 3.12 at one size of the environment, which is an
allocator's. Twenty shapes moved by 5% or more at the instructions 0.0.25's wheel counts,
which is where each build placed its loop, and none is charged to a change. Slower: on 3.15 ten
thousand integers 36%, list[None] 24%, list[str] 18% and the list nested twenty-five deep 7% to
11%; on 3.14 list[None] 31% and list[int | None] 7%; on 3.13 list[bool] and list[None] 20%;
on 3.12 list[int | str] 10%; on 3.11 a JSON array of int | str | None 7% to 8%. Faster: on 3.15
list[bool] 23%, list[int | str] 17% and {str: int, int: bool} 7%; on 3.14 list[float] 15%
to 16%, list[str] 14% and {str: int, int: bool} 5%; on 3.13 list[float] 12%, list[int | str]
8% to 9% and the JSON array 5% to 6%; on 3.12 list[int | None] 5%.
Added¶
-
A relation from finitely many constants reads each value. A subject built from literals,
None,bool, fixed sequences, sequences of one exact length, closed records and unions of them, holding at most sixty-four values, is related by the membership of each where both deciders decline: the nested one-item list[[[["1"]]]]a translation from JSON Schema writes isnot_subsetoflist[list[list[list[int | float]]]], where it stayedundecided. A supertype holding a predicate, a class or an attribute is not read this way. 47 ofvalgebra-jsonschema's undecided containment questions are decided by it, none against a label. -
An integer bound past 64 bits is held up to
2**120.Annotated[int, Le(9223372036854776000)], the largestint64as JavaScript prints it, issubsetofAnnotated[int, Le(18446744073709551615)]and the conversenot_subset, where both stayedundecided: a bound is read within2**120of zero, a Pythonintpast the 64-bit range among them. Past2**120a bound still declines, and a constant, a key and a step are still read within 64 bits. -
A recursive subject is narrowed twice where once found no value. Where every reading left a relation undecided and its subject holds a reference, the subject is unfolded twice before the cut, and a value of its difference with the supertype refutes: the JSON values are
not_subsetofunion(complement(list), Annotated[list, MaxLen(2)])met with them, on[1, 1, 1], where it stayedundecided. A decided pair pays one comparison for it. -
A split's halves are asked of their parts. Where every set the supertype negates leaves its halves undecided by the rules and the set representation, each half is asked of its parts, a union supertype narrowed to the branches it meets, with no split below:
Jthe JSON value isnot_subsetofunion(R("a"), intersection(J, complement(R("b")))),R(w)the closed record{"ref": Literal[w]}, where it stayedundecided. It refutes 9 ofvalgebra-jsonschema's undecided containment questions, each a label its results page shows wrong, and loses none. -
A pair the deciders declined is split on a set its supertype negates.
U <= Tis asked asU & C <= TandU & ~C <= T, for aCthe supertype holds under a complement, soJthe JSON value issubsetofunion(Literal[2], intersection(J, complement(Literal[2]))), where it stayedundecided: the excluded middlevalgebra-jsonschemawrites foranyOf [Y, not Y], which decides 182 of its containment suite's undecided questions, none against a label. A refuted half refutes the pair. -
A set inside
cthat holds a value is refuted below the complement ofc. ForJthe JSON value andreca record of a named field and a pattern-keyed clause overJ,{"foo": Literal[1], "vroom": Literal[2]}isnot_subsetofcomplement(intersection(rec, J)), where it stayedundecided: it lies insiderec, by a proof past the structural rules, and holds a value. It is the pairvalgebra-jsonschemaasks for a constant belownot, and 44 of its containment suite's undecided questions are decided by it. -
A meet of sequences is read as the one sequence of its items' meet.
intersection(list[J], union([], list[str]), Annotated[list[Any], MinLen(1)]), forJthe JSON value, isnot_subsetofintersection(list[J], union([], list[rec]))for a recordrecwith a required key, on["x"], where it stayedundecided. It is howvalgebra-jsonschemawritesminItemsbeside the items, and the tuple form is read alike. It is read so wherever it stands, as a record's field, a list's items or a mapping's values:intersection(dict[str, J], {"a?": intersection(list[J], union([], list[str]), Annotated[list[Any], MaxLen(5)])}), a closed object with a bounded array property as the companion writes it, issubsetof{"a?": Annotated[list[str], MaxLen(5)]}, and the same object underMaxLen(6)isnot_subsetof it, on six words, where both stayedundecided. -
Every sequence of a meet is read at once. For
Jthe JSON value andrecthe recordintersection(dict[str, J], {"t": str}),intersection(list[str], Annotated[list[Any], MinLen(1)], list[rec])issubsetofnothing, where it stayedundecided: each pair of its members holds a value, and the three hold none. It is the shapevalgebra-jsonschemawrites forminItemsbeside two item types.
Fixed¶
-
A long key is cut where a message writes its location. A string key past eighty characters is written in
str(error)and in each item'smessageas a subscript of its first eighty,['kkk...], and thepathkeeps it whole. A JSON document holding one key of a hundred thousand characters over a thousand failures built a 100 MB message at the raise. -
The failures under one key share its string in
errors. Each item'spathnames the key whole, and the items under one mapping entry hold onestrfor it rather than a copy each, soerrorsgrows with the failures and not with their product with the key's length. -
Long text is rendered from its head in a value summary. A
str,bytesorbytearraypast eighty items is rendered from its first seventy-nine, which reach the summary's eighty characters, rather than rendered whole and cut: a 10 MB string held a thousand times in a failing list took 17 s to report. The summary is the same but for its quote, whichreprpicks from the head alone where a single quote lies past it.
0.0.25 - 2026-11-09¶
A release of answers, with thirty-three additions and no node. Thirty-one of them read a
pair 0.0.24 left undecided, from a meet of a kind with members of that kind and a bound
written over every value read within the rest of its meet to a mapping's clauses beside a
table, and two build what 0.0.24 refused: a class reached again through a type alias,
and that bound met with str as a map key.
Over the 60,000 pairs each generation of a fuzzer draws, the relations give 1,766 answers
more than 0.0.24 on the second and 698 more on the first, and the JSON Schema containment
suite, read through valgebra-jsonschema, proves 107 more of its labeled inclusions and
refutes 145 more, with no proof against a label. One answer 0.0.24 gave on those pairs
reads undecided: the law A <= (A & ~B) | (A & B) over a union of float refinements
met with the JSON values, which 0.0.24 proved by not reading that a float refinement holds
a value, and which the query's budget does not reach once it does. Seven entries are
security fixes, and their advisories go out with the release.
Against 0.0.24 built here from its tag, on CPython 3.15, the instruction gate's workloads
count from 78.31% fewer instructions, a list of refined elements, to 1.01% more, a map
keyed by a language, each within its ceiling, and the whole steps asked of the sets count
10.54% fewer. The profiled wheel counts the one int 11.91% fewer, a wide record 7.57%,
the error report 4.18% and the JSON document 1.73%, and the build 0.25% more. On the
profiled wheels of CPython 3.11 through 3.15 a validator of one scalar kind is its type
test and counts 19% to 22% fewer, for a load and a comparison every other call pays at
its entry: two instructions, union 0.7% to 0.9% and literal 0.4% to 0.5%. A list of
refined scalars counts 66% to 75% fewer. A mapping counts twenty instructions more a
call, 0.2%, where a list of records reads its node once and counts 4.7% fewer, and a
relation between two built validators 0.2% to 0.4% more. A list nested twenty-five deep
counts 0.62% more on 3.13 alone, and reads 3.0% fewer cycles. The JSON shapes that count
higher do so at one size of the environment and not at the other, which is an
allocator's. On the free-threaded 3.14 and 3.15 a count of a shape of a few thousand
instructions does not repeat, and the two that read higher twice, a relation and a
mapping, read within 2% in cycles. A refusal reported over a value nested twenty
thousand deep counts 69% fewer instructions and takes 24 us where 0.0.24 takes 64 on
CPython 3.15: a union counts how far its branches went only between two that went past
its location, and moves the branch it reports where 0.0.24 copied it at every level.
One cost is named. A relation the set representation declines reads more before it declines: of the 840,000 calls the fuzzer's second generation asks, on profiled CPython 3.14 wheels built here, 295 take five times 0.0.24's time or more and 5 ms or more, up to 45 ms, nearly all a decline 0.0.24 also gave, and the generation takes 24% more time in all where the first takes 14% less; that time is spent in the readings the additions name.
Read on the wheels PyPI serves, two environments of each release on each of CPython 3.11
through 3.15, on an AMD Ryzen 7 PRO 7840U under WSL2, the shapes that count fewer
instructions take less time in both: a list of refined scalars 41% to 73%, building a
union 68%, one scalar 18% to 23% on 3.12 through 3.15, a membership test 17% to 24%,
refined fields 14% to 19% and a list of records 7% to 11%. Twenty-one shapes moved by 5%
or more at the instructions 0.0.24's wheel counts, within 0.6%, which is where each build
placed its loop, and none is charged to a change. Slower: on 3.15 list[bool] 31%,
{str: int, int: bool} 9% and list[int | str] 8%; on 3.14 list[str] 16%; on 3.13
list[float] 11%, list[int | str] 10% and a list nested twenty-five deep 7%; on 3.12
list[None] 17%; on 3.11 list[float] 16%, the list nested twenty-five deep 6% and
list[int] refusing a JSON document 6%. Faster: on 3.15 list[str] 15%, list[None]
20% and ten thousand integers 26%; on 3.14 list[None] 24%, list[int | None] 12% and a
relation between two lists 9%; on 3.12 list[float] 12% and list[int | str] 9%; on
3.11 list[bool] 10% and list[int | str] 9%.
Added¶
-
A length or a pattern written over every value and met with
stris a map key.{intersection(str, Annotated[object, MinLen(2)]): int}builds and keys the words of two characters or more, as{Annotated[str, MinLen(2)]: int}does, the two mapssubsetof each other both ways, where the key was refused as narrowing the keys it governs. Its complement met withstrbuilds too. Alone, or met with a union such asstr | byteswhose other kind it narrows, the bound stays refused, and so does an order bound met withint. -
A bound written over every value and met with a base is that bound over the base.
intersection(str, Annotated[object, MinLen(2)])andAnnotated[str, MinLen(2)]aresubsetof each other both ways, and so are the same length met withbytes, a list or a tuple, its complement met withstr, andintersection(int, Annotated[object, Gt(0)])withAnnotated[int, Gt(0)], where the meet readundecided. Met with a set or a dict, whose lengths the set representation does not count, it staysundecided. -
A union holds a value whichever member its constants list first. A record whose field is
intersection(X, B) | intersection(X, complement(B))isnot_subsetofnothingon a value ofX & B, where it readundecidedwhen the other branch came first. -
Zero is a multiple of an exact
FractionorDecimalstep.Annotated[int, MultipleOf(Decimal("2.5"))]andAnnotated[int, MultipleOf(Fraction(1, 3))]arenot_subsetofnothingand ofstron0, where they stayedundecided. -
A meet of a kind with members of that kind is read as those members.
intersection(int, Annotated[int, MultipleOf(0.5)])isnot_subsetofnothingon0, as the refinement alone is, where the meet stayedundecided. -
A class reached again inside a
typealias is tied by the alias.Box[Tree], withtype Tree = int | Box[Tree], builds the boxes holding a tree, and a dataclass naming itself throughtype Rest = Node | Noneis checked in depth, where each was refused as a class reached again while its own fields are being built. A class naming itself with no alias between is refused, since nothing ties that cycle. -
A word's length range is outside a table holding fewer constants.
Annotated[str, MinLen(1), MaxLen(1000)]isnot_subsetofLiteral["a"], on"b", where it stayedundecidedpast aMaxLenof 512. -
A pair asked through a complement is read by the parts it turns to. For
B = union(Annotated[int, Ge(2)], Annotated[int, Le(3)], Annotated[dict, MaxLen(2)]), whichintissubsetof,complement(B)issubsetofcomplement(int)andintersection(int, complement(B))ofnothing, where each stayedundecided. -
A supertype's clause of constants its subject never spells is beside it.
dict[Annotated[str, Regex("c")], str]issubsetof{"c?": int | None | str, Literal["a"]: bytes}, where it stayedundecided. -
A mapping of words under a length counting each is their record.
Annotated[dict[Literal["a"], int], MinLen(1)]issubsetof{"a": int}andnot_subsetofnothing, andAnnotated[dict[Literal["a", "b"], int], MinLen(2)]issubsetof{"a": int, "b": int}, where each stayedundecided. -
A meet supertype and a union subject are read a member at a time.
list[int]isnot_subsetofintersection(union(complement(list[J]), Annotated[list, MaxLen(2)]), J)for the JSON valuesJ, on[1, 1, 1], andunion(Annotated[str, Regex("a")], Annotated[float, MultipleOf(0.5)])ofAnnotated[float, MultipleOf(0.5)], on"a", where each stayedundecidedwith a member refuted. -
A clause's key split between clauses of a supertype is covered.
dict[Literal["a"] | P, int]issubsetof{Literal["a"]: int, P: int}forP = Annotated[str, Regex("b")], so a record'sclose()is related back to it, andValidator(dict[object, S]).open()ofValidator(dict[str, S]).open(), where each stayedundecided. -
A clause whose key holds no value and an optional field holding none carry no entry.
dict[intersection(Literal["a"], Literal["b"]), int]anddict[intersection(str, int), int]aresubsetof{}, and{"a?": Never}ofdict[Color, bool], where they stayedundecided: each holds the empty dict alone. -
A field's name is read as a word of a clause narrowed by a language.
{"a": int}issubsetofrecursive(lambda t: union(int, {Annotated[str, MaxLen(1)]: t})), as of one such mapping, where a reference in the way left itundecided. -
The complement of a table holds a plain value of a kind it has no constant of.
complement(Literal[Color.RED])isnot_subsetofstr, onNone, and ofunion(str, int), where each stayedundecided. -
Two attribute records share no value where a shared attribute holds none. A protocol with
x: Literal[Color.RED]issubsetof the complement of one withx: Literal[Color.GREEN], where it stayedundecided, as two records requiring one key already read. -
A meet of refinements of one base is read as the one they are.
intersection(Annotated[dict, MaxLen(2)], Annotated[dict, MinLen(2), MaxLen(3)])isnot_subsetofnothing,intersection(Annotated[int, Le(5)], Annotated[int, Ge(5)])ofAnnotated[dict, MinLen(3), MaxLen(5)], and a list of a refinement of a union whose branches are refinements ofnothing, where each stayedundecided. -
A mapping's clauses are read beside a table and over a language of keys.
Validator({Literal["a"]: str}).open()isnot_subsetof the same overbool, on{"a": "s"}, a recursion overAnnotated[str, Regex("a|b")]keys of one overRegex("a"), on{"b": 1}, and{"b": str}issubsetof{complement(Literal["a"]): anything}, where each stayedundecided. -
A class holds no boolean but through the order of
bool.booltakes no subclass, sointersection(K, bool)is empty andsubsetofnothingfor a class with a plain metaclass, where it readFalseandundecided. -
A float refinement and a float step over the integers hold a value.
Annotated[set[Annotated[float, Ge(0)]], MinLen(1)]andAnnotated[int, MultipleOf(0.5)]arenot_subsetofnothing, where they stayedundecided. -
A plain value of a kind is outside a table of another exact type.
list[str],boolandAnnotated[int, Ge(2)]arenot_subsetofLiteral[Color.RED], andboolofLiteral[2**63], where they stayedundecided. A literal pins its constant's type. -
Two sequences meet in nothing at a position each of their values has.
[int, None]issubsetof the complement ofrecursive(lambda t: list[t]), andintersection([int, None], R)is empty, where the first stayedundecidedand the second readFalse. A length bound names those positions:Annotated[list[int], MinLen(1)]issubsetof that complement, and of the complement oflist[str]. -
A position or a clause holding no value is read as what it leaves.
list[N], for anNwith no finite value such asrecursive(lambda t: tuple[t]), issubsetofAnnotated[list[int], MaxLen(0)], anddict[str, N]of{}, where they stayedundecided. -
A mapping's own lengths refuse a length its subject holds.
Annotated[dict, MaxLen(2)],Annotated[dict, MinLen(1)]andAnnotated[dict[str, int], MinLen(1)]arenot_subsetof{}, on a dict of one key, where they stayedundecided. -
A set's own lengths refuse a length its subject holds.
set[Literal[1, 2]]isnot_subsetofset[Literal[1]] | set[Literal[2]], on{1, 2}, where it stayedundecided, in a millisecond at 256 members against seventeen. -
A set of one member and a mapping of its required fields hold a value.
Annotated[set[tuple[int]], MinLen(1)],Annotated[{"a": int}, Len(1, 1)]andAnnotated[dict[bool, int], MaxLen(1)]arenot_subsetofnothing, where they stayedundecided, andAnnotated[{"a?": int}, MinLen(0)]of{"a": int}, on{}. -
A refinement only the sets read holds a value a refutation stands on.
recursive(lambda t: union(Annotated[str, Regex("a")], tuple[t]))isnot_subsetofstr, by("a",), where it stayedundecided. -
The complement of a set proved empty is every value.
complement(S)for anSis_emptyproves empty relates asanythingdoes, where it read for up to a few seconds and stayedundecided. -
A meet is read as a member below all the others. Where the pair declined everything else,
A & Banswers asAwhereverAis proved belowB.Color & (str | Color)isnot_subsetof a protocol its members do not carry, a true refutation lost in 0.0.23, and a list of an enumeration met with the class's complement reads as the list. -
A table of constants beside what holds them is the table.
intersection(str, Literal["a", "b"])answers asLiteral["a", "b"]does, the spelling a translation of anenumof strings writes. A relation between two of 60 and 400 words read 79 ms on 0.0.24 and 3.5 ms on 0.0.23, for an answer it reads in 1.6 ms, and a thousand drawn pairs that stayedundecideddecide. -
A supertype proved empty is the bottom. A schema
is_emptyproves holds no value, so what is below it is what is belownothing:strisnot_subsetof a protocol whoseyis itself, where it stayedundecided. A relation ofintagainst a recursive attribute record with no value read for up to 9.7 s on 0.0.23 and answers at once. -
A leaf is decided beside what stops the pair. A pattern below a pattern, a
boolbelow a bound overint, and every other pair only the sets read, stayedundecidedbeside a recursion, a class key or a third attribute record, since the pair's own reading stopped there:tuple[bool, R]belowtuple[Annotated[int, Lt(8)], R], and{"a": P, "b": J}below the same record over a wider pattern, the object a JSON Schema writes most. A pair everything else declined asks the sets of each goal the rules decline with no reference in it. -
A sequence or a mapping is refuted below a union on a value of one item.
list[bytes]isnot_subsetofJ | list[J], the shape of a field holding a document or a list of them, on[b""], andlist[bool]oflist[list[dict]] | list[list[dict[str, int]]]on[True], a pair 0.0.24 lost and 0.0.23 answered. Each branch holds[], so none drops out of the union, and no set is built.
Changed¶
- A note in 0.0.24 was wrong: it lost answers it gave. Its section says of a relation's reading
that "No answer it gave moves." Four pairs 0.0.23 decided read
undecidedon 0.0.24, among themlist[bool]belowlist[list[dict]] | list[list[dict[str, int]]], a list of an item outside every branch. The note stands where it was published, and this release decides all four again.
Security¶
-
The module loads in the main interpreter of a process, once. A legacy subinterpreter, which is what
mod_wsgiruns an application group in, loaded it, and every interpreter after the first to build read that one'styping:Validator(Annotated[str, Regex("a")])built asstrand admitted"b", andValidator(Any)refused every value. The pattern was dropped so on 0.0.17 through 0.0.24, every published wheel read on CPython 3.12. An embedder callingPy_Initializeagain afterPy_FinalizeExended the process in the next build, read on 0.0.24. Both raiseImportErroratimport valgebra; the main interpreter loads it whichever imports first. -
Each key of a parsed object is its own value to the walk's memo.
is_valid_jsonanswered one key of an object with the answer kept for another, where two members of a schema read a recursive key language:{K: int, complement(K): str}, forK = recursive(lambda k: union(Annotated[str, Regex("b+")], [k])), admitted{"b": 0, "0": 0}and refused{"b": 0, "0": "x"}, againstis_validofjson.loadsand againstvalidate_jsonon the same text. The answer was wrong on 0.0.19 through 0.0.24, every published wheel read, on CPython and PyPy alike. The memo keys a string by its text. -
What a relation over a float's bound or a step assumes of a subclass is stated. A step met with bounds is proved empty over the builtin's residues, and a subclass with a
%of its own is admitted by it, andnp.float64compares an integer past2**53rounded where the bound is read exactly. Both answers stay, inside the assumption the soundness page names, and known-unsound tests pin them. -
A proof between a record and a mapping narrowed by a language names what it assumes.
dict[Annotated[str, Regex("a")], int]issubsetof{"a?": int}, and{"a": int}of that mapping, on 0.0.24 as here. Astrsubclass with a__hash__or__eq__of its own stands against each: a key of the textano lookup of the name finds, and a key equal to the name holding another text. The answers stay, since refusing them gives up every proof betweenpropertiesandpatternProperties, over keys JSON gives none of these for; the soundness page states the assumption, and known-unsound tests pin both cases. -
A dict's entries are read from its storage on PyPy. PyPy's
PyDict_Nextanswers each value with a lookup of its key, so a dict holding two keys that reach one name through a slot a deleted key left read one value for both, and{str: int}admitted{Plain("a"): "s", Folded("A"): 1}, which CPython refuses on"s". The answer was wrong on every PyPy wheel, 0.0.1 through 0.0.24. The scan readsdict.items. -
A required field is paid for by the entry its name finds. A dict can hold two keys that reach one name, since
str's==and a subclass's own need not agree: withPlainastrsubclass andFoldedone comparing by its folded case,{Plain("a"): 1, Folded("A"): 2}has no keyb, and{"a": int, "b": int, str: int}admitted it, as{"a": int, "b": nothing, bytes: int}did while proved empty. The answer was wrong on 0.0.19 through 0.0.24, every published wheel read. Every reading of a record reads a name as the dict answers it, and the other entry as a key no field declares, so{"a": int, str: str}admits{Plain("a"): 1, Folded("A"): "s"}, and{"a": object}refuses a dict holding both keys by naming the extra key, where it named a mutation of a value nothing moved. -
np.float64is afloatto the relations, as it is to the walk.intersection(np.float64, float).is_empty()wasTrue, withnp.float64(1.0)in both;np.float64wassubsetofcomplement(float)andnot_subsetoffloat, and a subclass offloatwas proved disjoint from it beside a class deriving from both. The answers were wrong in 0.0.23 and 0.0.24. Its__base__isfloating, so a reading along the chain found no builtin. A class with none there takes its kind from a builtin its order names, which CPython refuses anmro()to add.
Fixed¶
-
Two equal
FractionorDecimalconstants built apart are one. Two validators ofAnnotated[int, MultipleOf(Decimal("0.7"))], each built with its ownDecimal, relatesubsetboth ways and are equivalent, where they compared==and readundecided. -
A pattern holding a lone surrogate is refused by its surrogate.
Annotated[str, Regex("\ud800")]was refused with "a pattern is matched against text, so write the pattern as a str", which it is. The message names the lone surrogate, a code point no UTF-8 text holds, which the pattern engine reads alone. -
A refined record or list display prints as the validator it builds.
reprofValidator(Annotated[Validator({"a": int}), MinLen(1)])wasAnnotated[{'a': int}, MinLen(1)], which Python 3.11'stypingrefuses to read back ('dict' object has no attribute '__module__') where 3.12 reads it. It printsAnnotated[Validator({'a': int}), MinLen(1)], which reads back as the same schema on every interpreter, and so does a fixed list. -
An annotation folds a recursion and its complement as its combinator does. For a recursive
K,intersection(complement(K), K)isnothingandunion(complement(K), K)isanything, andAnnotated[complement(K), Validator(K)]andUnion[complement(K), K]stood as written: the complement law reads a recursion through its definition, which the annotation's build held and did not pass. Each spelling of one meet or one join compares equal. -
A class applied past its type parameters is refused. For a
NamedTupledeclaring no parameter,Point[str]is an aliastuple's own subscription makes, and its validator wasPoint's, dropping the argument:Validator(Point[str]) == Validator(Point). It raisesNotImplementedErrornaming the count, as an alias applied past its parameters does. -
A recursion with an arm narrowed past words is refused as a map key.
dict[recursive(lambda t: union(Annotated[int, Ge(0)], tuple[t, ...])), int]built, where a key narrowed by a number's bound is refused where it is written, and its map's relations declined where the key partition decides them:dict[int, int]against it readundecided, which{-1: 1}refutes. It raisesNotImplementedError, asdict[Annotated[int, Ge(0)], int]does. -
A signal from an element's
reprraises out of the message.Validator(int).validate([x]), for anxwhose__repr__raisesMemoryErrororRecursionError, reported[<X instance at 0x...>]on 0.0.24, sincereprlib, which renders a container, reads everyExceptionas an element that cannot render; the two signals raise, as they do from the value's own__repr__. An element whose__repr__raises an ordinary exception prints as<unrepresentable>, the word for a value whose__repr__raises, with no address. A validator'sreprraisesMemoryErrorwhere Python cannot give a field name's or a pattern's text room, where it printed Rust's spelling of the text. -
A key past the digit limit is its hexadecimal text in a path.
Validator(dict[str, int]).validate({10**5000: 1})refuses the key, and on 0.0.24 its path held the key as anint, whichjson.dumps(err.errors)andrepr(err.errors)refuse past the interpreter's limit on the decimal digits it converts. The path holds the key's hexadecimal text,'0x31e2...', as the message writes it; the text indexes nothing, and no JSON document holds such a key. -
A failure inside a key ends its path at the key.
dict[tuple[int, ...], list[int]]refuses{("x",): ["y"]}at position 0 of the key and at position 0 of its value, and on 0.0.24 both items held the path("('x',)", 0), a place in the value. The key's item ends at the key,("('x',)",), since no subscript reaches into a key, and its message names the place in it:at ('x',), key[0]: expected int, got 'x' [int_type]. -
An allocation Python refuses inside a call raises
MemoryError. Where the interpreter could not give memory to an object valgebra builds -- a schema's, a report's, a parsed document's, a relation's answer, a rendering, an error's attributes -- the call raisedPanicException, aBaseExceptionthat neitherexcept MemoryErrornorexcept Exceptioncatches, and ended the process where even that exception could not be built. -
What a marker or a class yields is read within the node bound. A grouped marker whose constraints never end was read until memory ended and the process aborted, with no Python exception, and so were a protocol's members and a named tuple's
_fieldsgiven an iterable that does not end; aTypedDictwhose__required_keys__never ends never returned. Each raisesValueError: schema is too largepast 100,000 items. -
A value sharing a sub-object answers as its copy past the walk's bounds. The walk's memo answered a definition at a value from any earlier walk of it, and a walk with less of the bounds left, which would stop on its own, found the answer instead: against
recursive(lambda t: union(int, list[t], list[union(t, str)])), a list sharing one inner list at two depths wasFalsetois_validand admitted byvalidate, and a member where the same value sharing nothing was refused withrecursion_limit. A document reaches it too, where the second list branch reads an inner list again:[[..., "s"], "s"]a hundred deep was refused byis_valid_jsonand admitted byvalidate_json. An answer is found by a walk with as much of each bound left as the kept walk used. -
A refusal names a refined branch's bounds and each clause reading a key.
union(Annotated[int, Ge(10)], Annotated[int, Lt(0)])read5asexpected one of: int, int, andcomplement(Annotated[int, Ge(0)])asexpected not int, in a set holding-1.{Literal["a"]: int, str: str}refused{"a": 1.5}asstring_type, naming one of the two clauses it read, and a key no clause held was refused for its value too. The first two readone of: int and >= 10, int and < 0andnot (int and >= 0), a key several clauses hold names each,one of: str, int, and a key none holds names the keys alone. -
A refinement of a refinement and equal constants past 64 bits are one.
typingflattensAnnotated[Annotated[X, a], b], and aValidatorbetween the two kept two nodes, so one set relates apart under two spellings andreprprinted what did not read back. The two are one node, and twoLiteral[2**63]from two objects one constant, sounion(lit(x), complement(lit(y)))folds toanythingas it does for5. -
A pattern over a Unicode class beneath lists reads in under a second. A product of two automata counted as one step whatever it holds, so a
\w*beneath four lists read 3.7 s before a bound declined the pair, where 0.0.22 declined at once. A build pays for a product by its table, and the pair answers in 0.5 s and is refuted, where it stayedundecided. -
A named tuple holds the positions its class stores.
_fieldsis an attribute any subclass can write, andplatform.uname_resultnames a sixth, computed on demand, over five stored items, soValidator(platform.uname_result)refusedplatform.uname(), on every release read back to 0.0.20. The positions are those of the class directly abovetuple. -
A relation over a large step keeps to the memory it may have. A
MultipleOf's table holds a list per residue, and an operation over it counted as one step of a build: two list bounds over a union of ranges beside a step of 4096, in about fifty nodes, read for over a minute, kept 6.4 GB, and under a limit on memory ended the interpreter with no exception, from 0.0.23 over integers and from 0.0.24 over floats. A build pays for a table by the residues and spans it holds, so such a pair declines within seconds, where a table under a thousand of them answers as it did.
0.0.24 - 2026-11-06¶
A release of value universes, with five additions and no node. What a format holds is
a set of Python values, so JSON's and TOML's are written in the algebra as it stands,
on a page of their own. The representation reads what such a set is made of: a whole
step over floats, a key narrowed by a pattern or a length, a Fraction or Decimal
bound over a float, and a meet of 112 ranges where six ended undecided. numpy's
generic builds as a class met with a record, and the same spelling reads JAX's and
PyTorch's arrays. PyPy wheels are built for PyPy 8.0 alone, on 3.11 and 3.12.
Against 0.0.23 built here from its tag, on CPython 3.15, the relations asked of the sets count 30.26% fewer instructions and the length bounds asked of them 66.52% fewer. The core workload, the other decision workloads and every binding shape count within 0.03%, and the profiled wheel counts what 0.0.23 counts, to the instruction. On the profiled wheels of CPython 3.11 through 3.15 the walk counts what 0.0.23 counts but where an allocator moves a shape that allocates, and the largest move that repeats at two sizes of the environment is 0.38%, a JSON document nested deep on 3.11, which reads 0.5% fewer cycles. On the free-threaded 3.14 and 3.15 a count of a shape of a few thousand instructions does not repeat, and the shapes that read higher twice read level in cycles, to 2.0% on a wide record, about the spread of one build read against itself.
PyPI's wheels for CPython on Linux x86_64, read in cycles against 0.0.23's at one count
(release step 9, an AMD Ryzen 7 PRO 7840U), walk some lists at another speed, by where each
build places a kind's loop. Slower: list[int | str] by 8% to 20% on 3.11, 3.12, 3.14 and
3.15, list[None] by 19% on 3.11 and 63% on 3.15, list[bool] by 12% on 3.11, and ten
thousand distinct integers by 35% on 3.15, where a thousand read the same. Faster:
list[float] by 12% on 3.13, and on 3.15 list[str] by 14%, list[float] by 15% and
list[bool] by 24%. Every other shape reads within 5%.
Added¶
-
A
FractionorDecimalbound over a float is decided. It is read at the float on the side the bound keeps, as Python's exact comparison does, soAnnotated[float, Ge(Decimal("0.1"))]is the setAnnotated[float, Ge(0.1)]is, andAnnotated[float, Ge(0.25)]isnot_subsetofAnnotated[float, Ge(Decimal("0.5"))], where both wereundecided. -
A relation reads a wider schema. The set representation takes a schema of up to 1024 nodes, where it took 64: a range of JSON integers with 112 others taken out of it is decided, in 2.5 ms, where six made it
undecided. A product is stopped by the work it spends, as it was, and a union's members are joined in rounds. A union of patterns reads their automata, so one of 300 proves its meet with a complement in about 100 ms where it declined in 13, and one of 512, past the bound, declines in about 110 ms where it took 14. -
numpy's own generic builds.
np.ndarray[S, np.dtype[T]]andnpt.NDArray[T]denote the instances ofnp.ndarraywhoseshapeis inSand whose elements areT's, by thekindand the width of the dtype, where both were refused. It adds no node: the class met with an attribute record, which the relations decide, sonpt.NDArray[np.float64]andnpt.NDArray[np.float32]share no value. An abstract scalar type is refused, and the elements are not read. -
A map key narrowed by a pattern or a length.
dict[Annotated[str, Regex("x-.*")], V]builds, where it was refused, and so doMinLen,MaxLenand the connectives over them, which name a regular language ofstrkeys. Two clauses whose keys overlap read the join of their values on the keys they share, so a key takes one answer, and the relations read the languages: the map above issubsetofdict[str, V]and the reversenot_subset. A key narrowed by a number's bound, a word's order or a callback stays refused. -
A step over floats is decided as a set.
x % n == 0holds of the whole floats of one residue class, so the float component holds a list of intervals per residue beside the floats no step holds, and bounds and steps are read together:Annotated[float, MultipleOf(1), Gt(30), Lt(31)]is empty,Annotated[float, MultipleOf(1)]isnot_subsetofAnnotated[float, MultipleOf(2)], and the complement of a range of JSON integers, anintthat is noboolor a float that is a multiple of one, is decided. A step that is fractional or past4096is left to the rules.
Changed¶
-
A relation builds less to answer, and declines a little less. A set's complement is built only where it is read: what a list's element leaves, and what one set leaves of another, are read a kind at a time, so a kind a set misses costs nothing. The relations of the JSON Schema containment suite read 38% fewer instructions, and what a relation keeps of its allowance decides a few it left
undecided. No answer it gave moves. -
PyPy wheels are for PyPy 8.0, on 3.11 and 3.12, on manylinux. A wheel is published for each series on x86_64 and aarch64, and each runs the product suite on every push and in the release. PyPy 7.3 and PyPy on musl install from the source distribution, which needs a Rust toolchain: no push ran 7.3, and nothing here holds a musl PyPy to load a wheel. Free-threaded 3.14 runs on every push as well, and the release runs the product suite on the free-threaded musllinux wheels, which it built and never loaded.
Fixed¶
- Importing the package loads less. It registers no
valgebra._error_hooksmodule, and on PyPy an import loads neitherimportlibnorwarnings.
0.0.23 - 2026-11-04¶
A release of decisions, with thirteen security fixes and a new floor: fifty
additions, two changes, thirty-two fixes and thirteen security fixes. The
relations answer where they answered undecided. A pair every decider declines
is asked in its other spellings, and again under a larger allowance; a meet
holding a complement is read as the relation it is; a union is narrowed by the
complements beside it and decided a part at a time; lengths and kinds are read
off the shapes that hold them; and a recursive reference refutes at any kind. Of
784,000 questions a drawn corpus asks, 33,995 ended undecided on 0.0.22 and
8,882 do here, and on 154,000 drawn seeds no answer 0.0.22 gave is lost or
flipped.
Seven of the security fixes are proofs a value refutes: a literal of a class with
an == of its own, two bounds compared where the walk reads an operand otherwise
or over lists, a class whose metaclass hid its hooks, a class given __slots__
after it was made, and an enumeration with an instance past its members. Five are
acceptances, a generic class reading a qualifier, a default or a list of types as
a value and admitting what the class refuses. The last is a walk under a lowered
recursion limit that ended the process on PyPy. Each names the releases it
reached. Python 3.11 is the floor, and 3.10 leaves the matrix.
Against 0.0.22 built here from its tag, the relations asked of the sets count 48.66% fewer instructions, the length bounds asked of them 13.75% fewer and the core workload 0.75% fewer. On the profiled wheels of CPython 3.11 through 3.15 a scalar, a record, a list of records and a list nested twenty-five deep count what 0.0.22 counts, to the instruction, but where an allocator moves a shape that allocates. A union counts 0.34% to 0.60% more and a union of literals 0.17% to 0.61%, for the two tests that read a tagged union at its tag, where a thousand records read in 0.14 us against 48; a recursive schema counts 0.44% to 0.87% more and a list of refined integers 0.43% to 0.55%. A relation between two validators counts 4.2% to 4.4% more at its root, for the class scope a root build holds and the two maps a query keeps its readings in, and the decision workloads 0.25% to 1.97% more, the relation matrix the most, for the readings a pair the rules decline is asked. A question every decider declines can take longer to decline: a few drawn answers went from under 5 ms to as much as 65 ms, each unchanged, while five of the six drawn corpora take 8% to 63% less time in all. On the free-threaded 3.14 and 3.15 a mapping counts 23% to 27% fewer and a list of records 8%, and a list nested twenty-five deep about 1% more.
Added¶
-
A value of the difference cut the other way refutes at any kind. A recursive reference is cut once to read a relation, and the difference that proves an inclusion holds values the real one does not, so where it held one at a kind the cut reaches the answer was
undecided. The pair is read again with the subject cut to nothing and the supertype to everything, a difference inside the real one, and a value of it refutes. A protocol whosexisrecursive(lambda t: [t])isnot_subsetofint, asrecursive(lambda t: intersection(union( Validator([]), list[t]), complement(None)))is ofstr, on[], where each wasundecided. The relations over no fixpoint read no more instructions; a corpus of purely recursive schemas read 8% more, and answered a quarter of what it leftundecided. -
A question undecided at an allowance is asked again with a larger one. A relation, an emptiness or an equivalence that ends
undecidedbecause a pair asked in its other spellings ran out of its 4,096 steps, while the question had steps of its own left, is asked once more with 65,536. A record a translation from JSON Schema guards to objects, itstaga number from2**53or any value but a number, isnot_subsetof a tree of whole numbers, on{"tag": "x"}, where it wasundecided. The first asking's answer stands wherever it decides. A question that staysundecidedis asked twice: the declines of a fuzzing corpus took 8% to 38% longer in total, the slowest of them about twice as long. -
An enumeration met with sets refusing every member holds no value. A meet holding a class is read through the complement law: it is empty where the class is below the complement of the other members' meet, which the bindings ask of an enumeration a member at a time. For an enumeration
Pairwhose members carry noxand a protocolHasXrequiring one,intersection(Pair, HasX)issubsetofnothingandis_empty, asPair <= ~HasXalready was, where the meet was undecided. -
A refinement of a union holds what its refined branches hold. A refinement of a union is the union of its branches refined, so it holds a value where a branch under its bounds does, and a branch so refined that holds a value of a kind the supertype holds none of refutes the pair on that value:
Annotated[int | str, MaxLen(1)]isnot_subsetofintand ofnothing, on"", andAnnotated[str | bytes, MaxLen(256)]ofbytes, where each was undecided. -
A shape beside a length bound it misses holds no value. A meet of a record, a sequence or a set with a refinement whose length bounds that shape's lengths miss is empty, read as the shape under the bounds is:
{"a?": int} & Annotated[dict, MinLen(2)]issubsetofnothing, asAnnotated[{"a?": int}, MinLen(2)]is, where the meet was undecided. -
A mapping holds no more keys than its key types hold apart. The relation reads a mapping's most keys as the emptiness reading does: its fields, and as many keys as each clause's key type holds apart, so
dict[bool, int]anddict[Literal["a", "b"], int]aresubsetofAnnotated[dict, MaxLen(2)], and the meet ofdict[bool, int]with that bound's complement is empty, where each was undecided. -
A meet that may hold no kind is below every set. A meet holds no kind a member cannot hold, and a complement none its inner set holds whole, so the integers met with the complement of
~str | Annotated[str, MaxLen(1)], which holdsstrs alone, aresubsetofnothing, and empty tois_empty(), where they were undecided. A meet of patterns overstrbeside~stris placed at once, before any pattern's tables are built. -
A Boolean term of length bounds over one base is read as the lengths it holds. A union, a meet or a complement of
MinLen,MaxLenandLenover onestr,bytes, or list or tuple of one element type holds the values of the base whose length lies in a union of intervals, so two such terms are related as their intervals are, at any length:Annotated[str, MaxLen(1000)]issubsetofAnnotated[str, MaxLen(64)] | Annotated[str, MinLen(65)], where it was undecided past the 584 code points the word automaton counts to, andAnnotated[str, MinLen(4000)]isnot_subsetofAnnotated[str, MinLen(5000)]. Such questions answer in microseconds where the automaton took milliseconds. -
A sized base written bare is read as its refinement under no bound. A word, a byte string, a list, a set and a mapping each have a length at least zero, so
strandAnnotated[str, MinLen(0)]are one set, and the relation reads them alike:strisnot_subsetofAnnotated[str, MaxLen(1000)]anddict[str, int]ofAnnotated[dict, MaxLen(2)], where only the refinement was refuted. A set's lengths run to the values its element holds apart, soAnnotated[set[int], MinLen(1)]isnot_subsetofAnnotated[set[int], MinLen(2)], on{0}. And a subject holding the empty container of its kind, a refinement under bounds that admit zero among them, is refuted below a supertype refusing it:Annotated[set[int], MinLen(0)]belowAnnotated[set, MinLen(1)]onset(), andAnnotated[dict, MaxLen(0)]below{"a": int}on{}. -
A word's length bound is counted by a table built directly. A length bound over
stris a table of seven states a code point, which the pattern compiler reached through one of some sixteen and refused past 255 code points after building it:Annotated[str, MaxLen(2000)]met with a record's field took 35 ms to be found too large, and the firstis_emptyof a record of length-bounded strings over the JSON value paid it again for each new validator. Built directly, a bound is read up to 584 code points and refused at once past them, and thatis_emptyanswers in a tenth of a millisecond. The table is built once a thread, so a relation asked again reads it back. -
A meet holding one complement is read as the relation it is.
R & ~Iis empty exactly whereR <= I, so where every decider declines a meet's emptiness,is_emptyand the relation belownothingask that relation's rules under the steps the query has left, as the relation is asked: a union of length bounds proved below another meets its complement in nothing to both. A meet of two records over the JSON value whose field holds acomplex, met with the complement of the record of JSON fields, issubsetbelownothing, as the relation between the two is, andAnnotated[str, Ge("\ue000")]met with the complement ofAnnotated[str, Ge("\ud800")]is empty. The complement of a callback, or of a class whoseisinstanceis code, is no set, and its meet is not read so. -
A class with one instance is its literal, and a
Truestep is the step1.type(...)andtype(NotImplemented)admit no subclass and make no second object, soinstance_of(types.EllipsisType)isLiteral[...]andinstance_of(types.NotImplementedType)isLiteral[NotImplemented], asNoneTypeisNone; each pair wasundecided.%readsTrueas the integer it is, sointis belowAnnotated[int, MultipleOf(True)], which wasundecided. A wholefloatorDecimalstep stays apart from the integer step:(2**53 + 1) % 2.0is0.0. -
A table of constants is read for its kinds at any width. The reading that finds a kind a schema holds no value of stops after 64 nodes, and a table of constants spent one a constant, so
complement(union(int, Literal[tuple(range(63))]))wasundecidedbelownothingthough everystris in it. A constant is a leaf whose kind is one question, and it spends no node now, so the complement isnot_subsetat every width. -
A
Fractionor aDecimalbound over the integers is read as a float one is. Python compares anintwith either exactly, so the set representation readsAnnotated[int, Gt(Fraction(1, 2))]as the integers from1, the setAnnotated[int, Ge(1)]is, andAnnotated[int, Le(Decimal("2.5"))]asAnnotated[int, Le(2)], where such an operand was left unread and the pairundecided. A subclass, an infinite or NaNDecimal, and a value past the integers the set representation holds are not read. -
A container holds no more items than its shape can name. A length bound over a sequence was read against the sequence's own lengths, and over a set or a mapping only where the element's values were counted.
Annotated[dict[str, nothing], MinLen(1)],Annotated[set[int & str], MinLen(1)],Annotated[dict[bool, int], MinLen(3)]and the closed{"a?": int}underMinLen(2)wereundecidedbelownothing. A set of an element with no value is the empty set alone, and a mapping holds no more keys than its fields and what each clause with a value can take, its key's values kept apart, so each is empty. -
Records told apart by a required key share no value. Two records requiring one key whose schemas share no value are disjoint, and two unions of them are read a record pair at a time, so two discriminated unions whose tags are apart meet in nothing at any width. Sixteen records a side were
undecidedbelownothing, the meet distributed into record meets past the work a decision may spend, and thirty-two below the other's complement; two hundred now decide in a few milliseconds. Where each record pins the key to one constant, the two unions are read at the tag, only records whose constants share a value read whole, so sixteen hundred a side answer in about a millisecond, the meet and the complement alike. -
A length every branch of a union leaves out refutes at any size. A refinement holding a value of every length its bounds admit was refuted by a length one bound leaves out, and against a union of bounds only as far as the set representation counts, about 1,400 elements of a list:
Annotated[list[int], MinLen(1)]belowAnnotated[list[int], MaxLen(1)] | Annotated[list[int], MaxLen(3000)]wasundecided. A union refuses a value each branch refuses, so the least length no branch's bounds admit, a branch of another kind admitting none, is the witness at any size, a gap between two branches among them. Bounds covering every length refute nothing. -
A meet holds the exact empty container its members each hold. The reading found the container's kind on a bare container member alone, and read each member two ways, so
Annotated[set[str], MaxLen(0)] & Annotated[set, MaxLen(1)]andAnnotated[dict[str, int], MaxLen(0)] & ~{"a": int}wereundecidedbelownothing, thoughset()and{}are in them. Each member is now read three ways for the exact empty container of a kind a member names: a refinement keeps it under length bounds that admit zero, and a complement holds it where its inner shape refuses it. Both meets arenot_subsetofnothing. A member the reading cannot read, a predicate among them, leaves the meet undecided. -
A literal holds its constant where its own walk admits it. The relations read a literal's constant as a value only under an equality they trust, so
Literal[Decimal("1.5")], aFraction, adate, aUUIDor a class with an__eq__of its own was neither empty nor inhabited, andundecidedbelownothing. The walk of the literal admitting its constant now proves the literal holds it: each of those isnot_subsetofnothing, and a literal of astrsubclass equal to"a"ofLiteral["A"]. A constant the walk refuses or raises on proves nothing, as before. -
A length the supertype's bounds leave out refutes at any size. A refinement whose constraints are length bounds alone, over a base holding a value of every length --
str,bytes, a sequence with a repeated element whose positions hold a value, a mapping with one clause keyed by everystr,bytesorint-- holds a value of each length its bounds admit, and one a bound of the supertype leaves out is a value outside it.Annotated[str, MaxLen(256)]isnot_subsetofAnnotated[str, MaxLen(64)]andAnnotated[str, MinLen(64)]ofAnnotated[str, MinLen(1000)], where the pattern a word's length is read as passed the state bound and declined;Annotated[dict[str, int], MinLen(1)]isnot_subsetofAnnotated[dict[str, int], MinLen(2)]and holds a value at all, which a bound over a mapping's clauses did not say. -
A union holding a complement is asked as its difference.
a <= b | ~cis(a & c) & ~bempty, which isa & c <= b, both ways, and a pair every decider declines is asked so wherecdenotes a set, then as that difference read empty the wayis_emptyreads it.anythingbelow~dict | xis the dicts belowx:dict | ~dict | x, which construction folds toanything, is refuted below~dict | xwheredictis belowxalone, as it was before{"a?": object}.open()came to spelldict[anything, anything]. The dict kind's top, a member of such a union, is~~dict, soa <= b | dictisa & ~dict <= b:X | dictis proved to hold everything whereXholds every value that is not a dict. A union of a predicate and its complement is not the top and is not read so. -
A set's and a record's lengths are read off their shapes. A set holds each member once, so it is no longer than the values its element holds apart, and a closed record's length runs from its required fields to all of them.
set[Literal[1, 2]]isnot_subsetofAnnotated[set[int], Len(0, 1)],{"a": int}issubsetofAnnotated[dict[str, int], Len(1, 1)],{}andAnnotated[dict[str, int], Len(0, 0)]are eachsubsetof the other, andset[Literal["a"]] & Annotated[set[int], Len(0, 1)]isnot_subsetofnothing, the empty set being in both, where each wasundecided. Literals are counted apart within one kind, since1 == Trueacross two. -
A schema meeting a complement's inner set is refuted below the complement.
A <= ~Basked the meetA & Bfor emptiness and read only its empty answer; an inhabited meet is a value ofAinsideB, outside~B, and now refutes the pair beforeA <= Bis asked: the rules alone refuteanything <= ~list[json], which the respelled pair answered after every reading had declined. -
An order bound over
strorbytesis decided as the words it admits. Python orders two words symbol by symbol, a prefix first, and the words on one side of a word are a regular set the set representation holds, soAnnotated[str, Ge("a")]isnot_subsetofAnnotated[str, Ge("b")],Annotated[str, Gt("a")]is equivalent toAnnotated[str, Ge("a\x00")],Annotated[str, Lt("")]issubsetofnothing, andstris belowGe("a") | Lt("a"), where each wasundecided. -
A record is refuted a shared field at a time past the node bound. Where both deciders decline a record against a record, each field the two declare is asked of the set representation alone, and one outside its counterpart refutes the pair on a subject that holds a value. A record of thirteen guarded integer fields,
~int | Ge(0)each and~int | Ge(-1)first, isnot_subsetof the same record withGe(0)first, where past twelve fields it wasundecided. -
A record the key partition cannot hold is left out of a meet of records. A meet is below the members it keeps, so a meet holding a record whose clause names part of a kind -- an opened record keyed by an integer -- beside a complement is empty where the set representation reads the rest empty.
intersection(dict[str, nothing], complement({}), Validator({1: str}).open())issubsetofnothing, where it wasundecided. -
A meet subject is asked narrowed by the complements beside its unions.
K & (~K | R)isK & R, and a meet on the left is now asked in that form: the guard a JSON Schema translation writes for an object keyword over a recursive JSON value,intersection(OBJ, union(complement(OBJ), R0)), issubsetofR0, and two such guards are below the record holding both keys, where each wasundecided. The narrowed meet is asked with steps of its own, and one asked inside another's question with that question's steps and trail, so a fixpoint met with the complement of its own lists issubsetof the fixpoint without them; and a query whose steps are spent reads its two lattice bounds again, so a subjectis_emptyproves is below every supertype and one meeting a set in nothing below its complement. -
A meet supertype is decided a member at a time. Where both deciders decline a pair whole, a meet on the right is asked one member at a time, and a member either refutes refutes the meet:
intisnot_subsetofintersection(Annotated[int, Ge(0)], Annotated[object, Predicate(f)]), where the predicate refused the whole meet a lowering and the answer wasundecided. -
A set reading's difference refutes at a kind no cut reaches. A recursive reference read by the set representation is unfolded once and cut beneath the container that holds it, which changes that container's values alone, so a value the difference holds at another kind refutes.
strisnot_subsetofrecursive(lambda t: union(Annotated[str, Regex("a")], [t])), and so isintof the same fixpoint overGe(0),MultipleOf(2)or a dict, record or tuple oft, where each wasundecided. -
A sentinel compares by identity. Python 3.15's
sentineldefines an__eq__that answers as identity does, so two sentinels are two values: the meet of their literals issubsetofnothing, and one's literal isnot_subsetof it, where both wereundecided. -
None's kind is the literal of its one value.NoneTypeadmits no subclass, soNoneis its one value, and the kind is below a set exactly where the walk admitsNone:Noneisnot_subsetofLiteral[Color.RED], andintersection(None, complement(Literal[Color.RED]))isnot_subsetofnothing, where both wereundecidedbeside a constant the set representation cannot hold. -
A finite set of constants misses a value of every kind with infinitely many. A literal holds values of its constant's exact type alone, so a fresh
object()is in no literal of a set and its complement holds a value, and a kind other thanNoneandboolholds one no constant equals. Socomplement(Literal[Color.RED])isnot_subsetofnothing, andintisnot_subsetofLiteral[Color.RED], where both wereundecidedfor a constant the set representation cannot hold: an enumeration member, anobject(), aFraction. -
The complement of a meet holds a complemented member's values. Pushed in, the complement of a meet is the union of its members' complements, so
complement(intersection(complement({"a": None}), complement({})))holds{}and isnot_subsetofnothing, where it wasundecidedafter a second spent on the records, which have no region to read it by. -
A pattern too large to build is read by its texts. A counted Unicode class under a repetition,
Regex(r"(?:\w{3,4})+"), is past the size the set representation builds an automaton to, so every relation against it wasundecided. A string subject's texts are put to the validator's own matcher, as a literal's value is: every text of a pattern that has at most 64, soRegex("a")isnot_subsetof it andRegex("abc|abcd")issubset, and otherwise a guess at one text, which names a value where the matcher admits it, so the pattern isnot_subsetofnothing. A guess the matcher refuses names nothing:Regex(r"a\bb")staysundecided. -
A meet of sequences each holding the empty one holds it. The empty list is a value of every list shape with no prefix and of every length bound that admits zero, so
intersection([], RI)withRI = recursive(lambda t: union(int, [t]))isnot_subsetofnothing, and so isrecursive(lambda t: intersection([], [t])), where both wereundecidedwhile the element was a definition being resolved. -
The set representation reads scalars nested past its depth. Its depth bound exists for the containers a build starts -- an automaton, a powerset, a record lattice -- and every node above one still counts, so a container is refused where it was; a scalar node past the depth starts no build and is read.
intersection(int, complement(intersection(int, complement(E))))withEthe even integers isnot_subsetofnothing, and the same over the literals{1, 2, 3}or a bound, where each wasundecidedonce the meets and complements nested the constants six deep. -
A sequence's length is read at both ends of a relation. A list bounded to length zero is the empty list, so
Annotated[list[None], Len(0, 0)]issubsetof a list of any element, and a list shape whose element has a value is refuted below a maximum length by one copy more than it admits, so a list of integers isnot_subsetof the same list underLen(0, 1)-- what a translation from JSON Schema writes formaxItems-- where both wereundecidedwhenever the element was one the set representation cannot hold. -
A refinement of a union is the union of its refined branches. A constraint is asked of one value at a time, so
Annotated[int | float, Ge(0)]is the non-negative ints and the non-negative floats, and is decided as each is:intersection(None, Annotated[int | float, Le(1)])is empty,boolissubsetofAnnotated[int | float, Ge(-2)], and the base written as a union issubsetof the union of the refinements both ways, where each of these wasundecided. A constraint is Python's own operation, whose error the walk reads as a failed check, soNoneunder any constraint but a predicate is empty:Annotated[int | None, Ge(0)]isAnnotated[int, Ge(0)]. -
A float bound over the integers is read at its floor or its ceiling. Python compares an
intwith afloatexactly, so the set representation readsAnnotated[int, Gt(0.5)]as the integers from1, the setAnnotated[int, Ge(1)]is, where a float operand over the integers was left unread and the pairundecided.Gt(math.inf)holds no integer andLt(math.inf)every one. -
A meet is refuted below a meet it shares no value with.
a <= bwitha & bempty holds only of an emptya, so where every decider declines a meet against a meet, a subject that holds a value isnot_subsetwhere the two meet in nothing. Two objects a translation from JSON Schema guards to their kind, each a recursive record with a tag of its own, arenot_subsetof each other, where all 28 pairs of eight such schemas wereundecided. -
A union in a meet is narrowed by the complements beside it.
k & (~k | x)isk & x, so a branch that is the complement of a member beside its union is dropped before anything is distributed, and any number of keywords a translation from JSON Schema guards to one kind is read as the meet of what they guard: an object schema with three guarded keywords, two of them tags fixed two ways, is empty, where a meet of more than two such guards wasundecided. A narrowed meet the readings leave undecided hands the meet as written to the readings after it, which distribute it through a reference. -
Two branches splitting a set by another are read as the set they split.
(r & ~b) | (r & b)isrwhereverbanswers alike however often it is asked, so a union holding two such branches is decided as that set: the recursive JSON value issubsetof its own split bybool, and a list of JSON values of its split bylist[int], where both wereundecided, and a value outsiderisnot_subset. A split by a predicate is not merged. -
A type defined in C lays down the layout its instance size says. Python refuses a class deriving from two types unless the layout one lays down extends the other's, and a static type lays down one of its own where its instance is larger than its base's.
complexmeets no JSON kind, sointersection(complex, int)is empty andValidator(complex)issubsetof the complement of a JSON value, where both wereundecided, and an exception meets no kind either.ValueErrorandTypeErrorcarry the layoutBaseExceptionlays down, and their meet is not called empty. PyPy names no size, so there these pairs areundecided. -
A pair every decider declines is asked in its other spellings.
a <= bisa & ~bholding nothing, so where the rules, the set representation and the parts all decline, a difference holding every value of some kind refutes the pair whatever shape the subject has, and against a complement~cthe pair is asked as the meet withcbelownothing, ascbelow the complement of the subject, and as that meet read empty the wayis_emptyreads it, a union a member at a time, soanythingis below the complement of a union of members empty to different readings.anythingisnot_subsetof the complement of a list of JSON values, where it wasundecided, and on drawn translation shapes the plain spelling of an inclusion, an emptiness, a disjointness or a union subject declines where another spelling decides about a tenth as often. -
A word boundary at an end of a pattern is read as the character it asks about. A pattern matches the whole text, so a
\bor\Bleading or closing it asks only whether the first or the last character is a word character, and the set representation reads it so:Regex(r"\bab\b")is the setRegex("ab")is, where both directions wereundecided. A relation turning on a boundary between two parts of a pattern declines. -
An integer step is refuted by a multiple the other step does not divide. A refinement of
intby one integer step and integer bounds holds exactly the multiples of its step between its bounds, so its emptiness is read exactly, and it isnot_subsetof a refinement carrying an integer step where one of those multiples is no multiple of that step:MultipleOf(5000)againstMultipleOf(3)at 5000, andMultipleOf(6)againstMultipleOf(2500)at 6, where both wereundecided. -
A union is decided a part at a time where the pair declines whole. A union subject is asked a member at a time and a union supertype is narrowed to the branches the subject shares a value with, by both deciders, where the set representation refuses the whole pair past its node bound or could only prove it for a reference it holds: a union of seven to two hundred tagged records against the same records shifted is
not_subset, a union of 32 or more patterns issubsetof a pattern each is below, andstrisnot_subsetof a fixpoint of lists beside a pattern, where all three wereundecided. The parts are asked while the query has a step left: a part is a reading no step counts, and a pair the rules spend every step on, five hundred tagged records against five hundred, has as many parts as members and branches. A union is refuted by a member whose refutation stands, whatever its other members' emptiness reads, so a union of a recursive schema and a pattern isnot_subsetofnothing.is_emptyreads a union a member at a time too, so a union the relation proves belownothingis read empty. -
A subject holding every value of a kind the supertype holds none of is
not_subset. Every kind is inhabited, soanythingand a complement of a schema missing a kind are refuted at a value of that kind against a supertype -- a union, a meet, or a recursive schema read through its definition -- that holds none:anythingandcomplement(J)arenot_subsetof the JSON universeJatb"", andanythingofcomplement(J)atNone, where all three wereundecided. A meet is also read by a member that is a union of kinded branches, so a list met withNone | ((int | float) & ~bool & bounds)is empty. -
A complemented union or meet is read with its complement pushed in.
complement(union(a, b))is the meet of the complements andcomplement(intersection(a, b))the union of them, and a relation with such a subject is decided where that reading is the supertype or has it among its members.complement(union(str, complement(list[list[int]])))issubsetoflist[list[int]], and the complement of a union issubsetof the meet of the complements however its members nest, where both wereundecided. -
A musllinux wheel for CPython 3.15, its free-threaded build and PyPy 3.12. The musl build image carries all three, and the release builds a wheel for every interpreter it carries, so an Alpine install of 3.15 takes a wheel where it compiled the source distribution. The release runs the product suite on the 3.15 wheel in
python:3.15-alpine. No Alpine image carries a free-threaded CPython or a PyPy, so the other two are built and not loaded.
Changed¶
-
The floor is Python 3.11. CPython 3.10 reached the end of its security support in October 2026, and the first release after that drops it, as
docs/dev/releasing.mdstates: no wheel is built for it, andrequires-pythonis>=3.11. Every release from 3.11 to 3.15 is supported, the free-threaded builds of 3.14 and 3.15 among them, and 3.16 runs as a forgiven prerelease lane. The readingstyping_extensionsgave a form only 3.10 spelled with an object of its own are gone with it, and the refusal of a+after a quantifier saysrereads it as possessive without naming the release that began to, since every supportedredoes. -
A class key opens and closes as a kind does.
dict[K, Any].open()isdict[anything, anything], and closing that gives{}, asdict[int, Any].open().close()does, where it came back asdict[K, Any].dict[complement(K), Any], which opens to the same term, came back as the other half and admitted a keycloserefuses, and it gives{}too, so the round trip is at most closing with no exception.{K: Any, str: int}keeps its exact round trip.
Fixed¶
-
openandclosegive one term however often they are applied.{anything: int, int: anything, complement(int): anything}closes to itself, its first clause claiming every key, where it closed todict[anything, anything]and a secondclosetook that to{}.{int: int, str: int, union(int, str): complement(int)}opens todict[anything, anything]in one application, where it took two. No first application admits another set. -
Every key reads alike over a class, whose complement law does not fold.
{complement(K): int, anything: anything}opens to one term however often it is opened, where a secondopenwrote a longer key over the same set, and closing it after opening gives what closing it gives, where the round trip kept the keysopenfreed. -
A standard-library value type is the class the interpreter's module binds. The relations read
Decimal,Fraction, thedatetimetypes,UUID, theipaddresstypes and thepathlibpaths as ordering, dividing and measuring as their==says, and found each by identity with the class its module binds insys.modules. A program's ownfractions.pyordecimal.py, beside its script, is imported under that name, so a class of the program's was read as the standard library's, its order and its equality trusted as a value type's. A module is now the standard library's where the import system loaded it from the directorysysconfig.get_path("stdlib")names, or froze or built it in, and a module of the program's own leaves its classes declined: beside aFractionof the program's comparing as5,Annotated[int, Ge(1)]againstAnnotated[int, Gt(Fraction(1))]isundecided,2being in the one and not the other. -
A refutation stands on a length every interpreter builds. A container holds its items in one allocation, which the allocator refuses past
sys.maxsizebytes, so CPython builds no list longer thansys.maxsize // 8and no set past about a fifty-third of it. The relations read a length up tosys.maxsizeas one a value has:Annotated[list[int], MinLen(sys.maxsize // 8 + 1)]wasnot_subsetofnothing, on a list no interpreter builds. A witness is now given a length at mostsys.maxsize // 128, which every kind reaches on every supported interpreter, and a pair whose witness is longer isundecided. -
A field wrapped past the qualifiers read is refused as too deep. A dict literal refuses
RequiredandNotRequiredon a field, read throughAnnotatedandReadOnlyup to eight layers. Past them the field was built with the qualifier dropped:{"a": ReadOnly[...[NotRequired[int]]]}eight layers down required the key the qualifier calls optional, and"a?"overRequired[int]the other way. The field is refused there as nesting too deep, as a wrapper naming itself already was. -
A
Decimalbound with a vast exponent is not rounded to anint. The rule that finds no integer between two bounds rounded each to anint, and aDecimaltakes time quadratic in its digits to become one:Annotated[int, Gt(Decimal("1e999999"))].is_empty()took 26 seconds, and a larger exponent did not end. Past 4,300 digits, CPython's own default for converting anintto text, the bound is not rounded and the rule declines. The answer above is read in a fraction of a millisecond. -
A quantifier
rerefuses for repeating no atom is refused.rerepeats an atom and refuses a quantifier on a quantifier,a{2}{3}ora**, as a "multiple repeat", and one on an assertion,^*or\b+, as "nothing to repeat". Each was built here with a meaning of this engine's,a{2}{3}admitting"aaaaaa", which norecall could check. Each now raises aValueErrorinre's words. A lazy quantifier,a*?, is read as before, and(?:a{2}){3}repeats a repetition in both. -
No value is longer than
sys.maxsize. CPython counts a length in aPy_ssize_tandlen()raises pastsys.maxsize, while a length bound was read up to 2**64.Annotated[str, MinLen(2**63)], which admits no value, was refuted belownothing, andlist[int],tuple[int, ...],set[int]andfrozenset[int]were refuted belowMaxLen(sys.maxsize)on a value one longer, which no container is. A length bound pastsys.maxsizeis now refused at build as one no value has, and a bound at it refutes nothing for being exceeded. -
A signaling
DecimalNaN is refused as a bound or a step, asnanis.Annotated[int, Ge(Decimal("sNaN"))]andMultipleOf(Decimal("sNaN"))were built and admitted no value. The conversion to a float that readsnanand the quietDecimal("NaN")raises for a signaling one, and every comparison or remainder with it raisesInvalidOperation, which the walk reads as a refusal. Both are refused at construction with theValueErrornangets, read byDecimal.is_nan, a subclass overriding that method included. -
A class prints as its name only where its name builds the meet. A class met with a shape or a record it does not declare printed as the class, which reads back as every instance of it:
intersection(list[int], Plain)asPlain,intersection(Plain, P)for a protocolPasPlain, andintersection(instance_of(Pair), tuple[bool]), for a named tuple declaring anint, asPair. A generic dataclass applied printed as its name,Box[int]asBox, which reads back as its parameters' defaults or is refused. A class now prints as its name where the name builds the class met with that member, and the meet prints whole elsewhere:intersection(list[int], Plain),intersection(Plain, object(x=int)),intersection(tuple[bool], instance_of(Pair))andintersection(instance_of(Box), object(item=int)). A union's branch label names such a meet by its members,list and Plain. -
An enumeration is its members to a refutation as to a proof.
Pair, anEnumwhose members carry nox, was proved belowLiteral[Pair.A, Pair.B]and that union below~Xfor a protocolXdeclaringx, and refuted below~Xitself, on an instanceobject.__new__makes past the members;Pair & Xwas refuted belownothingand proved below~X | int. An enumeration read as the union of its members is that union on both sides:Pairis below~X, and no relation of the class stands on an instance its members are not. A member is read as it stands, so one given anxrefutes the class below~Xas it refutes its own literal. -
A frozen dict literal's refusal names the schemas that admit one. On 3.15,
frozendict(a=int)was refused with a pointer to the dict literal{"a": int}and todict[K, V], both of which refuse every frozen dict, since no node reads a frozen dict's keys. The refusal namescollections.abc.Mappingandinstance_of(frozendict), which admit one whole. -
A type variable is its own class's parameter.
class IntBoxOf(Box[int], Generic[T])reuses theTits base declares a field with, andtypingreads the two as two parameters:Box[int]closesBox's, andIntBoxOf's is another, the same object in another scope. Every field was substituted through one table keyed by the variable, soIntBoxOf[str]was refused as bindingTtointandstrat once, and so was a base applied to its class's parameters crossed. Each class keeps a scope of its own, a base's arguments read through the class deriving from it, and a field is substituted in the scope of the class that declares it:IntBoxOf[str]holds anintat the base's field and astrat its own. A class two bases reach under two arguments is still refused. A PEP 696 default naming an earlier parameter takes that parameter's binding in the same application: withUdefaulting tolist[T],Pairs[int]readsUaslist[int], applied directly or as a base applied short. -
A member deep by a clause's key alone is left out of the last thinned reading. A meet the set representation cannot read whole is read without the members it cannot hold, a superset whose emptiness proves the meet's. A map's key is read for the labels it covers, never descended, so a member at the edge of the depth by its key alone was kept, and beside literal-keyed records the meet with it was not proved empty where the meet without it is: 0.0.22 declined a share of the emptiness proofs 0.0.21 made over maps --
{}alone, outsidedict[Literal[True], None]'s complement. A last reading counts a key as a level and leaves such a member out, after the two that keep it. -
A length bound no automaton could count to is refused before it is built. A
strorbyteslength bound is read as a pattern counting code points or bytes, and the pattern's compiler unrolls the count into that many copies before any limit is read:Annotated[str, MinLen(999_999)]againstMinLen(1_000_000)held three gigabytes, and a bound past the address space aborted the interpreter with no Python exception, on every release. A table counting to a bound holds a state for each count, so a bound past the 4,094 a table of 4,096 states counts to is refused before its pattern is written, as a sequence's bound already was, and the compiler is held to the size the table build is held to, for every pattern. Both relations answer at once. -
A constant the walk stopped on proves and refutes nothing. A literal is decided by walking its constant through the supertype, and a predicate that raises on the constant stops that walk, which refuses the value from the set and from its complement alike. The relation read the refusal as a value outside the set:
Literal[5]wasnot_subsetofT | ~TforTanintrefined by a predicate raising on every value, a union holding every value, and through the respelling of~(T | ~T) <= ~Literal[5]as its contrapositive, the empty~(T | ~T)was refuted below it too. The constant is read as a complement reads its inner walk: refused only where the walk decided it, admitted only where a branch admitted it, and neither otherwise. The same for an enumeration's members,None, and the texts a pattern too large to build is read by. -
A bound whose operand orders on its own renders marked. A bound of a subclass of
int,float,strorbytesprinted as the builtin's bound, but where the subclass writes a comparison or a remainder of its own the walk reads that one first, so the two are two sets:Ge(RevInt(5)), withRevIntordered the other way round, holds0, and its meet withcomplement(Annotated[int, Ge(5)])printed as one that reads back empty. The operand prints as a literal of it does,Ge(<RevInt: 5>), a syntax error where it is read; a subclass keeping the builtin's methods prints as before. -
Opening or closing a schema twice gives the schema once did.
Validator({"a": int, "b?": anything}).open()keptb, which the closed record says something of, beside the catch-all the opening wrote, which says the same ofb; a secondopendropped it, soo.open() != oby==and their hashes differed. The first rewrite drops a name the clauses it writes already say, and either operator applied twice is the term it gave once. A supertype that folds todictthis way is still decided against a complement of a union: where every decider declines,~(~x | y)is asked asx & ~y, so it issubsetofdictwherexis a set of dicts. -
annotated_types.doc()is ignored under annotated-types 0.8.0. Wheretyping_extensionshas noDocto lend, the release makes a class of its own namedDoc, which earlier releases namedDocInfo, andAnnotated[int, doc("a count")]was refused as a constraint valgebra does not check. It documents an annotation and excludes no value, and is ignored asDocInfois. -
A string a
typealias substitutes is refused as a forward reference.type Keyed[T] = dict[str, T]applied to""raisedSyntaxErrorfromtyping, which reads a string it substitutes as the text of an annotation and finds no expression in that one, whereKeyed["int"]was refused as the forward reference it is. Both raiseNotImplementedError; a string for a parameter the alias's value does not name is never read. -
A meet two of whose members share no value is below anything at once. A meet subject asked each member against the supertype before reading its own emptiness, so
intersection(complement(bool), float, dict[str, X])against a large recursive schema walked that schema for seconds before the meet's emptyfloat & dictpair answered it. The pair is read first. -
A table of constants below a complemented table is one question.
Literal[0, ..., 3999]againstcomplement(Literal[-1, ..., -4000])is the two tables sharing no value, which the bindings answer for both tables at once: it is decided in 3 ms, where each constant was asked against the whole other table and the relation took 1.2 s, quadratic in the width. The meet's emptiness,intersection(A, B)belownothing, read the tables whole already. -
A counted Unicode class written as an ordinary bound builds. The walk's pattern compiles under a size limit of 32 MiB, three times the
regexcrate's default, which refusedAnnotated[str, Regex(r"\w{1,255}")]and every count past\w{0,209}whileretakes them.\w{1,1000}is refused as before, naming the limit. A validator keeps every pattern's program, so its patterns compile within 256 MiB together, eight programs at that bound, each text once, when it is built: a record of sixteen^[\w.-]{1,n}$fields keeps 43 MB and builds, and eighteen\w{1,255}fit while a nineteenth is refused there, where a hundred held a gigabyte and aborted the interpreter at the first value. -
One depth bound raises one type. An annotation nested past
MAX_SCHEMA_DEPTHraises theValueErrora schema built past it raises, at the bound and past it, where 129 levels and more raisedNotImplementedError. A class whose own type appears in its fields is refused withNotImplementedErrorwhere it is reached again while its fields are being built, under the type arguments it is applied to, rather than after descending to the bound:Chain[int]namingChain[int]is refused, andBox[Box[int]]builds. -
A length bound equal to a whole number is that length, and a truth value bounding a number is the integer it is.
lenis anint, soAnnotated[str, MaxLen(2.0)]admits whatMaxLen(2)does, and is built as it, where it was refused; andtypingcachesAnnotatedby equality, so a correctMaxLen(2)was refused in a process that wroteMaxLen(2.0)first. An integralFractionorDecimallength reads the same way, and one equal to no whole length is refused, as is a number of any other type, whoseint()and==are its own.Le(True)isLe(1)to the decision, soAnnotated[float, Le(True)]isnot_subsetofnothing, where it wasundecided. -
A recursive definition being resolved is read as empty at positive positions only. The emptiness decision reads a definition it is resolving as empty, the least fixpoint, and a relation it asks on the way could drop a branch, a component or a slot of the relation's supertype by that reading, which narrows the supertype and can refute a relation that holds. While a definition is being resolved, such a part is told apart from the subject by the kinds each may hold, a reference read through its definition. No released answer is known to have been refuted this way.
-
A reading that cannot decide a meet hands it to the next. A meet's readings are each sound alone, so one that ends undecided passes the meet on rather than answering for it.
intersection(union(complement(DN), DB), Validator({"a": int}), complement(dict)), withDNandDBmappings keyed byLiteral["a"], issubsetofnothing, as on 0.0.21, where 0.0.22 distributed the union, ended undecided and asked nothing after it: of the answers 0.0.21 gives on 60,000 drawn record schemas, 0.0.22 left 136undecidedthree combinators deep and 153 four deep. -
The emptiness decision reads a reference in the complement law as construction does. A recursive schema is a set where its definition is one, and the decision reads it through its definitions, so a meet of a recursive schema holding a class with its own complement is empty:
x & ~xwithx = intersection(json, list[complex])isis_empty(), where it wasFalse. -
is_emptyreads a complemented union as a relation belownothingdoes. A complemented union is empty where its complements, pushed one level in, meet in nothing as they are built, which is how the relation reads it belownothing, socomplement(union(complement(str), complement(intersection(json, complement(str))))).is_empty()isTrue, where it wasFalsebesiderelation_to(nothing) == "subset". -
A relation the two schemas settle as written is never undecided for want of a step. A schema against a union that holds it, a meet against one of its own members, and a schema against itself are answered before any rule spends the decision budget. Records a translation from JSON Schema guards to objects and nests four deep are
subsetof a union holding them, and a recursive record met with a nested closed one issubsetof that recursive record, where 0.0.21 and 0.0.22 spent the budget on the meet's members and answeredundecided. -
A
Lenwhose minimum is below zero is refused.annotated_typesunpacksLen(-1)to no lower bound, soAnnotated[str, Len(-1)]built the barestrwhileMinLen(-1)was refused for naming no length a value can have. Both raise thatValueError. -
A required key whose name ends in
?renders marked. No dict display requires such a key, since the display reads a trailing?as optional, andreprprintedTypedDict("TD", {"a?": int})as{'a?': int, str: anything}, the display of a record whoseais optional. It prints{<required: 'a?'>: int, str: anything}, a syntax error where it is read, as a constant whosereprwould read back as another value does.
Security¶
-
A constant proves its literal only where the values equal to it read alike.
Literal[CI("a")], withCIastrsubclass whose==ignores case, holdsCI("A"), whichRegex("a")refuses; the literal wassubsetof that pattern, and its meet with the pattern's complementis_empty(). The same held ofint,floatandbytessubclasses with an==of their own against bounds, lengths and steps, and of a literal against another literal of a class whose==is not transitive. The answers were wrong in 0.0.1 through 0.0.22. A proof by the constant stands where the values==joins to it read alike to the supertype's atoms: an exact builtin, a builtin subclass keeping the builtin's==(anIntEnum), a standard-library value type (Decimal), or identity. A class is a standard-library type by identity with the class its module binds, never by the__module__it states. -
Two bounds over lists or tuples are not compared.
Annotated[list[object], Ge([2])]holds[2 + 0j], whose one item equals2, andAnnotated[list[object], Ge([1])]does not, since ordering2 + 0jagainst1raises; the first wassubsetof the second. The answer was wrong in 0.0.1 through 0.0.22. A sequence orders item by item, so no order between two list or tuple bounds is an order of the values; two set bounds compare by inclusion and stay decided. -
Two bounds are compared only where each operand orders as the walk reads it.
Annotated[int, Ge(Mod7(1))], withMod7anintsubclass equal to every integer congruent to it modulo 7, admits1, since1 >= Mod7(1)reads the stored1; it was equivalent toAnnotated[int, Ge(8)], becauseMod7(1) == 8. That answer was wrong in 0.0.1 through 0.0.22. Astrorintsubclass ordering by its own methods was read the same way, so a tighter bound was proved below a looser one that a value refutes, and an empty interval was reported inhabited. A bound whose operand is a builtin subclass with an==, an order or a rounding of its own is compared with no other bound, and so is one whose operand is of a class of no builtin, unless that class is exactly one of the standard library's value types (Decimal,Fraction, the dates): Python implies no relationship among a class's comparison operators. -
A class is read where Python dispatches its hooks, not through its metaclass. Whether a class overrides
isinstance,issubclassor==, whether a builtin subclass's__len__and__iter__are the base's own, which slots and descriptors its namespace holds and in what order its bases stand were read throughgetattron the class, which asks the metaclass first. Python dispatches each through what the type's own namespaces hold along the order it laid down, and asks no__getattribute__, so a metaclass answering with the plain one hid the class's own: a class whose__subclasscheck__answersTruewas decided above a classisinstancesays it is not above, two instances of a class with an equality of its own were two disjoint literals, astrsubclass whose__len__answers0metMaxLen(1)with"abc", and an order the metaclass reported decided a meet empty that held an instance. A hidden__subclasscheck__was read wrong in 0.0.1 through 0.0.22, and a hidden__eq__in 0.0.10 through 0.0.22. Each is read asinspect.getattr_staticreads it now, at no cost to a class whose metaclass istype. -
A class's layout is the one Python laid down. A class given
__slots__after it was made -- by a decorator, say -- lays down no slot, yet was read as laid out: its meet with any slotted class, and its relation to the complement ofint, were decided empty, beside instances Python builds of both. Such a meet was answered empty in 0.0.14 through 0.0.22. A class whose metaclass'smro()leaves out the builtin it derives from was read as laid out on nothing, though every instance is laid out on that builtin, and a slot whose descriptor an assignment replaced was read as unset rather than as the value every instance reads. The layout is read off__base__and off the member descriptors Python makes with a class. -
An enumeration making an instance past its members is not their union. An
Enumwhose_missing_returns a new instance for any value was decided equivalent to theLiteralof its members, thoughE(5)is an instance of it and of no member's literal; an enumeration whose metaclass leaves a member out of its iteration was decided below the members it lists. The answers were wrong in 0.0.10 through 0.0.22. An enumeration is read as the union of its members only where its_missing_isEnum's and its metaclass's__iter__and__call__areEnumMeta's. -
An enumeration with a subclass is read as its class. An enumeration with members is read as the union of them because the class makes no other instance. No class statement derives from one, but on CPython 3.15
__bases__assigned to a plain class does, and that class's own constructor makes an instance of the enumeration that is no member:Huewas decidedsubsetofLiteral[Hue.RED, Hue.GREEN]with such an instance in the first and not the second. The answer was wrong in 0.0.10 through 0.0.22. An enumerationtype.__subclasses__lists a subclass of, as it stands when asked, is read as the class it is. -
A
TypedDictqualifier given as a default or asextra_itemsis refused. A class left unapplied takes each parameter's default, which reaches its fields as an argument does, andNotRequired[int]as the default read as the item's own: the key turned optional,{}admitted and the class proved equal to one declaringa: NotRequired[int], though the runtime keepsarequired; aRequireddefault turned an optional key required, and a dataclass's field dropped the qualifier. The reading was wrong in 0.0.21 and 0.0.22. A qualifier as a parameter's default is refused as the same qualifier written as the argument is, bare or underAnnotated.RequiredandNotRequiredasextra_items, which PEP 728 calls an error, are refused there too, where they built as the type they wrap;ReadOnlyis read through. -
A
TypedDictqualifier given as a type argument is refused.Required,NotRequiredandReadOnlyqualify an item where it is declared, and the typing spec admits them nowhere else.Holds[NotRequired[int]], for a genericTypedDictdeclaringa: X, read the qualifier as the item's own:aturned optional and the class equaled one declaringa: NotRequired[int], where the runtime keepsarequired; a dataclass applied to one dropped it. The reading was wrong in 0.0.21 and 0.0.22. A class applied to a qualifier, bare or underAnnotated, or a base written applied to one, is refused, naming the class the field is declared in. -
A class over a list of types or a signature is refused applied. A
TypeVarTuplestands for a list of types, andRow[int, str]binds it to(int, str), so a fieldtuple[*Ts]istuple[int, str]; the parameter was bound to the argument at its position, soRow[int, str]held{"a": (1,)}, refused{"a": (1, "a")}, and equaledRow[int]. The reading was wrong in 0.0.21 and 0.0.22. A generic class whose parameters are not allTypeVars is refused where it is applied, takes a default for one, or is a base written applied, as an alias declaring one already is; written bare, it is read where no field names the parameter. AParamSpecalike. -
A type parameter's default written as a string is refused. PEP 696 makes a default a type expression, and a string there a forward reference, which the runtime keeps as written. A field that is the parameter alone read it as the value it is: under
W = TypeVar("W", default="int"),a: Wwas the literal'int', admitting the word and refusing every integer, in aTypedDict, a dataclass and aNamedTupleleft unapplied. The reading was wrong in 0.0.21 and 0.0.22. It is refused as a forward reference, as the same string written as the argument is and aslist[W]already was. -
A
TypedDict'sextra_itemsgiven as a string is the type it names. PEP 728 takes a type expression there, and a string where one goes is a string annotation, which the runtime keeps as written. It was read as the value it is:extra_items="int"built{'total': int, str: Literal['int']}, admitting the word as an extra value and refusing every integer, in the class statement and the functional form alike and in a subclass inheriting it. The reading was wrong in 0.0.10 through 0.0.22. It is resolved as the class's own annotations are, in the module that defines the class. A class whose extra items are its own type is refused as a class whose fields name it is, with the hint to write it withrecursive(...). -
A deep walk on PyPy stops where PyPy has stack to answer. PyPy sizes the stack its C-API calls may use by the recursion limit, and a walk that reached it before its own bounds ended the process: under
sys.setrecursionlimit(60), validating a list nested fifty deep did, on every PyPy wheel, 0.0.1 through 0.0.22. The walk now asks PyPy's stack check as it goes deeper, and refuses atrecursion_limitwhere PyPy has no room, so the value is no member andvalidateraises an error the caller catches. Under the default limit the answers are unchanged, and CPython is untouched.
0.0.22 - 2026-10-27¶
Three meets decided where the relations declined, and a relation 0.0.21 made
dearer: three additions and one fix. A meet is disjoint from what one of its
members is, a meet of records holds the dict of the fields they require, and
a meet of a few unions is decided clause by clause, so the meets a
translation from JSON Schema writes when it guards each keyword to its kind
answer where they answered undecided. The fix reads the depth the set
representation refuses off a schema before anything is built, where 0.0.21
built the reading and lowered the supertype for an answer that could only be
undecided.
Against 0.0.21, two records spelled OBJ & (~OBJ | R) & (~OBJ | REQ) are
related in 76% fewer instructions, and their recursive spelling in 52% fewer,
which is 32% more than on 0.0.20. The decision pairs that reach the set
representation count 0.26% more, for the depth read off each schema before
it is built and the switch that reads a meet by its members' kinds; the
relations that hold and the corpus asked of the sets count 0.04% and 0.06%
more, and the refuting and length-bound workloads 0.27% and 0.15% fewer.
Every other shape the instruction gates count reads within 0.02% of 0.0.21.
The profiled wheels' walk on CPython 3.12, 3.14 and 3.15 counts what 0.0.21
built from its tag counts, to the instruction, but where an allocator moves a
shape that allocates and in the layout 3.15's build gives the walk: a
literal's check one instruction more, a recursive schema's twelve fewer.
Added¶
- A meet is disjoint from what one of its members is. A schema a union
holds as a branch, written as a meet, is read by its kinds as the meet's own
members are, so
intmet with a union of two string patterns each guarded to strings,intersection(str, union(complement(str), Annotated[str, Regex(p)]))as a translation from JSON Schema writes apattern, is empty where it wasundecided, and an integer isnot_subsetof such a union. - A meet of records holds the dict of the fields they require. Records met
in a meet, open ones among them, are one record whose fields hold what every
record gives each name, through its field or the catch-all over its kind, so
the meet is empty where a required field has no value and holds the dict of
those fields where each has one. Two open records over a recursive universe
that fix two different tags are
not_subsetof each other where they wereundecided, and{"tag": str}met withdict[str, int]is empty. - A meet of a few unions is decided clause by clause. A meet whose unions
span four clauses at most, no branch of them a meet or a union, is read as
their union, each clause decided on its own, where only a union beside a
recursive reference was. A translation from JSON Schema guards each keyword to
its kind,
OBJ & (~OBJ | R) & (~OBJ | Q), so two tags fixed two ways meet in nothing and one tag beside a required one holds a value, where both wereundecided. A relation whose subject the set representation reads without such a meet, which the rules now find a value of, is not built for the reading that can only find it inhabited.
Fixed¶
- A relation the set representation refuses for depth costs a walk, not a
build. 0.0.21 read a meet nested past the depth the set representation
descends without the members past it, building the members it kept, and
lowered the supertype as well, where the answer could only be
undecided. A relation between two records each spelledOBJ & (~OBJ | R) & (~OBJ | REQ), as a JSON Schema translation guards a keyword to its kind, counted 85% more instructions than on 0.0.20. The depth is read off the schema before anything is built, and a reading the rules find a value of is built only for a relation whose supertype the set representation reads: the same relation counts 76% fewer instructions than on 0.0.21 and 55% fewer than on 0.0.20, with the same answer. Its recursive spelling,$ref'd as a JSON Schema translation writes it, counts 52% fewer than on 0.0.21 and 32% more than on 0.0.20, the rules reading the meets the decision asks on the way. A meet holding a member past the depth is read without it whatever else the member holds, and a member whose deepest node is a mapping's key is kept, where each was left unread.
0.0.21 - 2026-10-26¶
Four relations decided where they declined, readings the typing spec gives
that the frontend refused or misread, and a wrong subset proof withdrawn:
four additions, one change, six fixes and two security fixes. A generic
TypedDict, dataclass or NamedTuple applied is read with its arguments in
place, and a meet holding a literal, a meet beside a member the set
representation cannot read, and a meet of records answer where they answered
undecided. A copy of a validator is the validator. The fixes read a type
alias unpacked into a tuple and a class whose __getattr__ answers every
name, and refuse three spellings that name no one set: Required and
NotRequired on one item, bare Generic, and a dict display whose two keys
build one key schema. The security fixes are a meet holding a union twice
beside a recursive reference, answered empty though a value is in it, and a
complement of a definition two of its members share, whose walk took seconds
near the depth bound. The entries under Security name the releases each
reached. Upgrade from any of them.
Against 0.0.20, a fifty-field TypedDict whose five optional fields are
refined compiles in 11% fewer instructions, and explaining a failure and
relating two validators count up to 0.5% fewer. Every other shape the
instruction gates count reads within 0.1% of 0.0.20, the profiled wheel's
flat, but a dataclass's compilation, 0.05% more for the test that reads
whether the class is generic.
Added¶
- A generic
TypedDict, dataclass orNamedTupleapplied is read with its arguments in place.Box[int]for a dataclassBox(Generic[T])with a fielditem: Tis aBoxwhoseitemholds anint, where it was refused, and so is a class deriving from one applied,class IntBox(Box[int]), or aTypedDictchild ofPair[int], however deep the derivation, which built nothing either: the field readTand was refused as a type variable. A parameter neither applied nor bound takes its PEP 696 default; one with none, named by a field of the class written bare, is refused naming the class and the variable, and so is a type variable two bases bind to two types. A generic classisinstancealone answers is refused applied, as it was. A genericTypedDictandNamedTupleneed 3.11. - A meet holding a literal is decided one constant at a time. Each
constant is walked through the other members: the meet is inhabited where
every member admits one, and empty where each is refused by some member. So
Literal["paid"] & ~(Literal["paid"] & J), for a recursive universeJthe set representation does not read deep enough, is proved empty where it was undecided, and so is a literal set minus the complements of that universe met into each piece, the schema a planner meeting every member with its universe builds. A refusal speaks for the literal only where nothing the member asks tells equal values apart, as a literal below a schema reads it, and a predicate that raises on the constant decides nothing. - A meet proved empty stays empty beside a member the set representation
cannot read. Two patterns no string matches both of were proved apart,
and beside a predicate, or beside a member nested past the depth the set
representation reads -- the complement of a literal met with a recursive
universe is one -- the meet was undecided. Such a member is left out of the
reading, which is a superset of the meet, so its emptiness is a proof, as a
meet of three members and as one
Annotatedholding all three constraints. The reading proves emptiness and only that: the meet without the member holding a value refutes nothing. - Records met in a meet are related as one record. The meet of two open
records whose catch-all is a recursive universe --
{"tier": Literal["free", "pro"], str: json}and{"tier": Literal["pro", "enterprise"], str: json}-- was undecided below{"tier": Literal["pro"], str: json}, minus it, and as one record minus the third below the other's complement. The records are met field by field into one record, a field holding what every record gives its name and missing only where every record lets it be, and the record rule relates that record as it relates one, so all three are proved. A member of another shape beside the records leaves the proof standing, and so does a meet below a complement, asked as the meet holding the complement's inner, as any other subject is.
Changed¶
- A copy of a validator is the validator itself.
copy.copy(v) is vandcopy.deepcopy(v) is v, as the standard library gives back an immutabletupleorfrozenset, where each built a new validator over the same schema, which held the same set and computed its hash and its per-node tables again.
Fixed¶
- An attribute a
__getattr__hook answers is never read as missing. A refutation about a class stands on a direct instance of it, and the relations read a name the instance's__dict__lacks, a slot left unset and a name a class without a__dict__does not define as able to be missing where the class defines__getattr__-- which answers exactly those lookups. So a class whose hook returns1for every name, refusing every subclass, was answerednot_subsetof a protocola: objectthat every instance of it satisfies, and its meet with that protocol's complement was answered inhabited, in 0.0.16 through 0.0.20. Beside such a hook a slot or a dictionary entry holds any value it is assigned and is never missing, and a name neither can hold is the hook's answer: such a pair answersundecided, and one refuted by a value an assignment puts there --a = "x"against a protocola: int-- staysnot_subset. - A
typealias unpacked into a tuple is the tuple it names.tuple[str, *Tail]undertype Tail = tuple[int, ...]buildstuple[str, *tuple[int, ...]], as every type checker reads it, where it was refused with a reason that was false of it: an applied generic alias splices with its arguments in place, a fixed tuple's alias splices its elements, and an alias of an alias is read through. An alias of something that is not a tuple is refused naming what it stands for, and so are aliases naming each other in a cycle and an alias that unpacks itself,type Rec = tuple[int, *Rec], which has no finite length. RequiredandNotRequiredon oneTypedDictitem are refused. The typing spec makes the pair an error, and the two read as different records -- the runtime's key sets take the key as required and pydantic as optional -- where the outermost was read. A qualifier nested in itself,Required[Required[int]], names one record and is read as the one qualifier.- A mapping names each key schema once.
close()of{str: anything, bytes: int, complement(str): anything}left two clauses overbytes, and itsrepr,{bytes: anything, bytes: int}, read back asdict[bytes, int], a smaller schema;openandclosefold two clauses over one key schema into one over the join of their values, so it closes todict[bytes, anything]. A dict display whose two keys build one key schema,{Validator(int): str, int: bytes}, is refused, as two keys that are one field name are. - A
recursivebody that never names the fixpoint is that body.recursive(lambda t: int)kept a definition no reference reaches and was not==toValidator(int); it isValidator(int), rendered asint. - Bare
typing.Genericis refused. It is the base a generic class derives from and no type, and it built anisinstancetest admitting an instance of every generic class.
Security¶
- A meet holding a union twice beside a reference is not proved empty. A
meet a recursive reference opens distributes each union it holds, and a
branch kept the other copies of the union it came out of, so where the union
stood twice -- bare, and inside another member -- a branch could be the meet
already being decided, met again with no constructor between, and read as
empty as a cycle under one is. So
intersection(FRAC, union(None, NUMBER), JSON), a fractional number met with a nullable number and a recursive JSON universe, was answeredis_empty() == Trueand"subset"ofnothingthough0.5is in it, in 0.0.18 through 0.0.20. A branch drops every copy of the member it distributes, which it is inside, and such a meet answers as its values do. - A complement walks a definition two members share once per room. A
complementreads its inner walk with a stop as a third answer, and took no stop the walk kept for a definition at a value, so where every walk of a shared definition stops -- near the walk's bound, and past it -- each level below was walked once per path.complement(recursive(lambda t: union(int, [t], [union(t, str)])))took 0.3 seconds to refuse a list nested 101 deep on the 0.0.17 wheel and 3 seconds at 102, a value its schema admits and thatdocs/guides/limits.mdstates the walk linear in, and a list nested 128 deep took longer than fifteen seconds on every release. The cost inside the bounds reached 0.0.17 through 0.0.20, and the one past them every release. A stop the inner walk kept answers one of its own kind with no more room, as the walk's own stops answer it: the complement costs what the walk costs, on every entry point.
0.0.20 - 2026-10-24¶
Three relations decided where they declined, one wrong subset proof
withdrawn, and a crash and an unread bound repaired: three additions, one fix
and three security fixes, and nothing removed or refused. A record against a
union of records it splits across, a table of constants minus constants, and a
mapping keyed by literals answer subset or not_subset where they answered
undecided, and so does a relation over a byte pattern whose automaton fills
the state bound. The security fixes are a literal proved below a predicate or
a protocol by running its constant alone through it, though the literal holds
every value of its type equal to the constant; a list read through a copy on
CPython 3.10 and 3.11, which a garbage-collector finalizer emptying the list
under the copy took down; and a constraint marker answering through a
__getattribute__ of its own, whose bound went unread. The entries under
Security name the releases each reached. Upgrade from any of them.
The walk reads the shapes a document is made of in fewer instructions, on the
profiled wheels of every CPython the release builds, against 0.0.19 built from
its tag: a mapping of one or two scalar clauses, as dict[str, int], 33% to
36% fewer with a global lock and 23% to 27% fewer on the free-threaded builds;
a list of TypedDict records 12% to 13% fewer, and 8% on the free-threaded
builds; a JSON array of records 2% fewer; and a list nested twenty-five deep 3%
to 5% fewer with a global lock. That list counts 0.5% to 1% more on the
free-threaded builds, in register moves the walk's layout makes, and reads
fewer cycles there. On 3.10 and 3.11 a list read through its copy counts the
three hundred or so instructions the copy spends holding the collector off: a
thousand elements of one scalar kind 1.4% to 1.6% more, of a union of scalars
and explained once refused under 1% more. Every other shape counts at most
0.15% more than 0.0.19, but the free-threaded builds' calls of under two
thousand instructions, which the allocator moves by a few per cent either way.
Added¶
- A table of constants minus constants is decided as the set it leaves.
intersection(Literal[0, ..., n], complement(Literal[0]), ...)taking every member away is proved empty at any length, where the set representation declined from twenty-one members, and a table minus some of its constants is below a table holding the rest and refuted by one missing a constant left. The rules read it by lookup, as they read two tables: a constant is taken away by its pool position, and kept only where the bindings say it is a value apart from every table taken away. - A record is decided against a union of records it splits across. A
record whose tag takes three literals is
"subset"of the three records that each fix one, and"not_subset"of three where one also requires a key the subject leaves free, where that answered"undecided";{"a": int, "c?": bool}is below a record requiringcbeside one leaving it out. A record whose fields each take two types is decided against its corners up to six fields, where four declined, and seven decline on the decision budget. Read as emptiness, a record minus the records that cover it is empty, so an open record minus the record of each constant its key takes is proved empty at any length, where thirteen declined. The split is Castagna's backtrack-free rule for records (ICFP 2023), run by the rules rather than by building the difference. - A clause keyed by literals is read one constant at a time. Two mappings
keyed by one literal are refuted under it at any depth:
dict[Literal["a"], ...]forty levels deep overintis"not_subset"of the chain overstr, where five levels answered"undecided". A record is refuted against a mapping keyed by literals on astrsubclass's key equal to a field's name, which the field reads and the literal does not, so{"a": int}againstdict[Literal["a"], int]answers"not_subset"where it answered"undecided"; anddict[Literal["a"], int]is below{"a?": int}by the rules, without the set representation.
Fixed¶
- The widest pattern automaton the state bound admits is built. A byte
pattern whose automaton gives every byte a class of its own reads 2,048
bytes a state, and the builder's limit was exactly
MAX_STATESsuch rows, so the 4,094- and 4,095-state tables were refused by the 4,160 bytes the builder keeps beside its rows, and a relation over such a pattern answeredundecided. The limit leaves room for them, and the state bound refuses a table at every width.
Security¶
- A literal is proved below a predicate only where it is its constant
alone. A literal holds every value of its constant's type equal to it, and
the relations proved it below a schema by running the constant alone through
it. So
Literal[0.0]was answeredsubsetofAnnotated[float, lambda x: math.copysign(1.0, x) > 0], though-0.0is in the first and not the second;Literal[Decimal("1.00")]was answeredsubsetof a predicate requiring two decimal places, thoughDecimal("1.0")is in the first and not the second; and the literal of an instance whose__eq__compares one attribute was answeredsubsetof a protocol requiring another, which an equal instance carries otherwise. The answers were wrong in 0.0.1 through 0.0.19, the last in 0.0.16 through 0.0.19. Such a pair answersundecided. A literal of anint, abool, astr,bytes,None, a nonzero float or anEnummember is its constant alone, and is decided as it was. - A list is copied for its walk with the collector held off before 3.12.
On CPython 3.10 and 3.11 a list one test settles --
list[int],list[date], a list of literals or of tuples of scalars -- is read through a tuple copy of it where the copy pays, and allocating the tuple may run a collection inside the copy. A finalizer that collection ran which emptied or regrew the list left the copy reading memory the list had freed, and the process ended; the copy reached 0.0.10 through 0.0.19. The collector is held for the copy alone and its state given back, at about ten nanoseconds a list; 3.12 and later and PyPy copy as they did. - A marker answering through a lookup of its own is read through
getattr. A constraint marker deriving from theannotated_typesvocabulary that answersge,max_lengthor another name through a__getattribute__of its own carries the name neither on its type nor in its dictionary, which is where the frontend read it from, soAnnotated[int, M()]withMansweringge=5builtintand accepted0. The reading was wrong in 0.0.11 through 0.0.19. Such a marker is asked for every name, as one with a__getattr__hook is, and buildsAnnotated[int, Ge(5)]; a marker read through the generic lookup is read as it was.
0.0.19 - 2026-10-20¶
A release of repairs: thirty-two fixes and eight security fixes, and nothing
added or removed. Eight answers were wrong in a way SECURITY.md scopes as a
vulnerability -- one wrong subset proof, six shapes that admitted a value
outside the schema's set, and a walk exponential in a JSON document's depth --
and each entry under Security names the releases it reached. Upgrade from any
of them.
The breaks are refusals, each of a spelling that built a validator reading
another set than the one written: Required or NotRequired on a field of a
dict literal, a type alias of an Annotated alias in metadata, a possessive
quantifier or a spaced count in a pattern, a ... after an unpacked tuple or
an unpacked tuple outside a tuple's arguments, a complex bound or step, and a
Decimal step over a float base. A Regex of anything but text raises when
the marker is made. Answers move where they were wrong: a complement reads its
inner walk in Kleene's strong logic, close reads the clauses admitting every
value as one, and a conjunct refutes beside one the rules decline. A repr
reads back as the schema it came from but for the forms the API reference
lists, a complement's expected names the set it excludes, a missing key is
spelled as the path spells it, and a set reports its failures in an order the
value fixes. Five costs that grew faster than a schema or a value -- a wide
union's ==, a refused union's labels, a wide record over JSON, a long literal
in a relation, and a chain of definitions -- grow no faster than it.
Fixed¶
- A signal raised while a predicate's error is named propagates. The
error's text was read through its formatter, which drops a signal its
__str__raises:validatereported apredicate_errorreading<exception str() failed>and the interrupt was lost, andis_validcalled the__str__for a text it never reports. The text is read where a violation is recorded, and a signal is raised. A__repr__returning astrsubclass is read for the text it holds, rather than formatted through the subclass's__str__, which put<unprintable ...>in the summary. - A signal while the first validator reads the special forms is raised. An
interrupt while
typing.Neverwas first read was folded into the form's absence, which the process kept: every laterValidator(typing.Never)was refused as a typing construct. The signal is raised, and the forms are read again by the next validator. - A relation raises a signal its reading of a class meets. A metaclass hook
raising on the class's
__eq__, or a__slots__whose iteration raised, were folded into an answer,undecidedor a verdict, and the signal was lost. They raise it, and an ordinary exception there declines the class's reading. - Pickling a
ValidationErrorleaves the error as it was. The reduction deleted the error's internal failures from the instance being pickled, which a thread reading the error at the same moment could meet half done. It pickles a copy of the state. - An integer key past the interpreter's digit limit reaches the path as an
integer. A key longer than
sys.set_int_max_str_digitsallows was named'<unrepresentable>', a string that indexes nothing. It is carried in hexadecimal, which the limit does not bind:pathholds the key, and the message writes it[0x...]. - A dict literal refuses
RequiredandNotRequiredon a field. A qualifier is read as the type it qualifies, so{"a": NotRequired[int]}built a record that requiresa, and{"a?": Required[int]}one whereais optional, in silence. The literal says whether a key is required by its?alone, so either qualifier on a field is refused, naming the key's spelling.ReadOnlyis read as before. instance_of(typing.Any)is the top whatever is imported. It was the top in a process that had loadedtyping_extensions, which importingannotated_typesdoes, and refused every value in one that had not. It is whatValidator(typing.Any)is, on every release whereAnyis a class.- A dataclass field declared
Annotated[Final[int], m]is read. The typing spec letsAnnotatedwrap a qualifier without changing it, and the field holdsAnnotated[int, m]; the class was refused as an unsupportedtyping.Final.Annotated[ClassVar[int], m]is still refused, in words that say why: it is a class variable to the typing spec and a field todataclasses. AProtocolmember declared either way is refused as one declaredClassVarorFinalis. - A
Regexmarker pickles and copies. Unpickling restored its slot bysetattr, which the immutable marker refuses, so neitherpicklenorcopyworked, and a schema holding one could not be sent to another process as a validator's own pickle refusal says to send it. It reduces to its pattern. A pattern that is not astr, such asRegex(123)orRegex(re.compile("x")), raisesTypeErrorwhen the marker is made, rather than at the build, and comparing a marker with anything but a marker returnsNotImplemented, so the other operand's__eq__is asked. A | ~Ais the top whereAis a union, andM & ~Mthe bottom whereMis a meet. Construction flattens a union into the join that holds it, so no single member wasA, and the fold declined:union(A, complement(A))withA = union(int, str)printedint | str | complement(int | str)and compared unequal toanything, though it is decided equivalent. The fold reads the flattened members, so==,hashandreprgive the bounds. A join of many complements is folded in time near-linear in its width, where the pair check was quadratic.- A chain of recursive definitions is checked in time linear in its length. The contractivity check walked a definition once per path to it, so a chain whose every link names the one before it twice took 0.27 s at eighteen definitions and doubled per link; the 128 a validator may hold never finished. It enters each definition once.
- A complement is below the complement of an empty refinement.
complement(Annotated[str, Regex("x"), MaxLen(0)])is the universe, since no string both matchesxand has no characters, yetcomplement(Annotated[str, MaxLen(0), str.isdigit])and the complement of a union of forty patterns were not proved below it in any release through 0.0.18. Two complements relate as their inner sets do the other way round, and there the empty refinement is the subject, whose emptiness the rule read without the set representation, the one reader of a pattern's shortest match. The rule asks it where the inner sets' relation declines, as the rule for a single complement does. - A constant prints whole in a
repr. A constant past eighty characters was cut where an error message cuts a value, soLiteral["x" * 100],Literal[10**100]andAnnotated[int, Ge(10**90)]printed a syntax error where they could have read back. A constant prints its ownreprin full, as a pattern and a field name already do; anintpast the interpreter's digit limit, whosereprraises, prints<unrepresentable>. - A literal of a builtin's subclass is not printed as the builtin's
literal. A literal admits its constant's own type, so
Validator(S("a")), withSa subclass ofstrthat writes norepr, refuses thestr"a", yet it printedLiteral['a'], which reads back as a schema admitting it, in 0.0.17 and 0.0.18; the same held for a subclass ofint,float,complexandbytes. Where the constant'srepris the builtin's spelling of it, the literal prints asLiteral[<S: 'a'>], a syntax error where it is read; a subclass whosereprspells it some other way prints by thatrepr. - A recursive schema's
reprbinds a name its body does not print. The back edge was bound toX, thenY,ZandT3, whatever the body printed, sorecursive(lambda t: union(None, {"c": X, "n": t}))over a classXprintedrecursive(lambda X: union(None, {'c': X, 'n': X})), which reads the class back as the back edge and rebuilds a schema refusing{"c": X(), "n": None}, in 0.0.17 and 0.0.18. Each binder is the first spelling of its letter,X,X_1,X_2and on, that no word of the render spells: a class's name, a constant'srepr, or a name the interpreter reads as that spelling under NFKC normalization, such as a fullwidthX. - A validator's pickle refusal sends a reader to the forms
reprcannot spell. It saidreprrebuilds every form but a class or a predicate, and the API reference lists seven, two of which read back as a different schema; it names that list now. The boundaries page counts the two quiet forms where it counted one. - A key that reaches a record's field name is that field in every
reading. A record read by scanning its entries, which is one beside a
clause that reads its keys such as
{"a": int, str: int}, took a key that is not an exactstrfor a field only where the key's own text named it, while the reading that asks the dict for the declared keys took it whereverd["a"]finds it. A key of another type that hashes and compares as"a", or astrthat spellsband compares asa, was fieldato{"a": int}and an undeclared key to{"a": int, str: int}, andvalidateagainst the second reportedmutated_during_validationfor a dict nothing had changed. Every reading resolves a key as the dict does. The soundness page adds the assumption the relations take for such a key: a key equal to a declared name is a string. - A set's failing elements are reported in an order the value fixes. They
were ordered by the first failure's value and code alone, so two elements
failing alike at different places,
(1.5, 2)and(2, 1.5)againstfrozenset[tuple[int, int]], kept the order the interpreter handed them over: two equal frozensets reported in opposite orders andfail_fastkept different errors, and with string elements the order moved withPYTHONHASHSEED. They are ordered by everything each failure says: the value, the code, the path inside the element, and what it expected. - Two spellings of one schema fold to one when composed.
Annotated[int, Ge(3), Ge(5)]andAnnotated[int, Ge(5), Ge(3)]are one schema to==, yet a union of the two validators kept both members, andunion(a, complement(b))stood unfolded for anaequal tob, where the same pair written as one annotation folds. The same held of two steps, of a map's literal keys,{Literal["x"]: int, Literal["y"]: str}against the keys written the other way round, and of either inside another schema. Composing interns one validator's constants into the other's pool, which can send two of them past each other, and a refinement's constraints and a map's clauses kept the order they held. Each set a composition renumbers is put back in the order construction gives it. - Two spellings that meet their recursive definitions in two orders are one
schema. A validator numbers its
recursivedefinitions in the order construction meets them, and==andhashread a reference by that number:union(r1, r2)andunion(r2, r1), a record{"a": r1, "b": r2}against its fields written the other way round, and every schema holding either compared unequal and hashed apart, thoughis_equivalentcalled them one set andreprprinted them alike, so the second spelling'sreprread back as the first and not as itself. Composing the two kept a copy of each definition:ab | baheld four members, andab | ~bastood unfolded beside anabequal toba. In 0.0.10 through 0.0.18, where the algebra page gave the order of a set's members as no difference; 0.0.17 and 0.0.18 called the union two schemas, and the record was never one. Two PEP 695 aliases spelled alike were two definitions too, in 0.0.10 through 0.0.18:A | Bheld two members and did not equalA. A reference is read through to the definition it names, the two tables' definitions paired one to one in the order construction numbered them; composing finds a definition the target already holds under that pairing rather than appending a copy, and an alias definition the table already holds is that definition. A comparison that would need more than the depth or the steps the limits page states answers no, as it did. - One schema prints one way, whatever order its sets were written in. A
union's literals printed in one order however they were written, and every
other set printed in the order its constants or classes were first named:
A | BandB | A,Annotated[int, Ge(3), Ge(5)]and the bounds the other way round, a map's literal keys and a meet's members were one schema to==andhashand two torepr. Within a set -- a union's or a meet's members, a refinement's markers, a map's clauses -- the members of one kind print in the order their renderings sort in, as a union's literals did, so a union of classes writtenDog | CatprintsCat | Dog. The members of different kinds keep the order they had, and every rendering reads back as the schema it came from. - A required key or a repeated element refutes beside a field the rules
cannot read.
{"a?": X} <= {"a": Y}answeredundecidedwherever the field's types were ones no rule reads, such as two predicate refinements, though{}is in the first and not the second; so did{"a?": int}against the same{"a": Y}, and[int, int, ...]against[Y, str, ...], which[1, 2]refutes. Required-ness was read only after the field's types were proved related, and a sequence's repeated element only after its prefix, though neither refutation rests on the other. Each is read beside it, and the three answernot_subset. A prefix no rule proves to hold a value, such as[X, int, ...], names no sequence for the repeated element to stand on, and staysundecided. - A complement's answer no longer depends on the order a value's parts are
read in. A walk inside a complement that stopped -- at the depth bound, at
a value holding itself, at a predicate that raised -- answered by whichever
part it met first:
complement(list[R])refused[deep, "x"]and admitted["x", deep], two equal dicts built in two orders answered apart, renaming a record's fields flipped the answer, andis_valid_jsonanswered by key order. A stop in one branch of a union that another branch admitted was read by a complement above it as its own. The inner walk is read in Kleene's strong logic: a part that refuses refuses whatever a part beside it stopped on, a branch that admits admits whatever another stopped on, and only a walk where nothing decided is a stop, refused with its code. The change admits values under a complement and admits no value the complement's inner schema holds. A value that moved while it was read is refused withmutated_during_validationwhatever the rest decided. - The clauses admitting every value close as one clause.
closeread each clause carryinganythingon its own, as the region it frees where its keys were the complement of the others'. So{str: anything, complement(str): anything}closed to{}, asdict[anything, anything]does, while the same pair besidebytes: int, or the top split overint,complement(int)andcomplement(str), kept every clause and admitted every dict. Those clauses are one clause over the union of their keys: the part over keys another clause claims stays, and the rest is the regioncloserefuses. The first shape closes as it did, the second to itsbyteskeys and the third to{}. - A bound or a step Python cannot apply is refused.
Annotated[int, Ge(1j)],Annotated[int, MultipleOf(1j)]andAnnotated[float, MultipleOf(Decimal("0.5"))]built validators that admitted nothing, andrelation_to(nothing)answeredundecided: Python raises on1 >= 1j, on4 % 1jand on1.5 % Decimal("0.5"). A complex bound is refused with aValueError, as a bound againstnanis, and so is a complex step; aDecimalstep over a float base is refused with aNotImplementedError, as a step over a base with no number is, and overint | floatit narrows the integers. BecausetypingcachesAnnotatedby equality,MultipleOf(2)built afterMultipleOf(2 + 0j)arrives as it and is refused with it, where it admitted nothing before; the message says so. - A relation over a long
Literalstring or bytes answers at once. The set representation built a literal's automaton a state per byte and minimized it before the first product refused it as past the state bound, soValidator(Annotated[str, Regex("a*")]).relation_to(complement(Literal["a" * 1_000_000]))took a second to answerundecided. A literal past 4,094 bytes, astrcounted in UTF-8, is refused before anything is built, and the same relation takes a tenth of a millisecond. So is a length bound over a list or a tuple past 4,094 elements, which built its automaton past the bound at 4,095 and 4,096. No answer moves. ==reads a wide union in one pass, whatever order it was written in. Equality matches a union's members as a set, and two spellings of oneLiteralwritten in different orders compared each member with every member left: 82 ms at four thousand members, four times as long at each doubling. A member is looked for only among the other side's members that hash alike, so the same comparison takes 0.4 ms. Two validators built alike match in place.- A refused union renders only the sixty-four labels its message names.
Every member's label was rendered and the ones past the bound dropped, so a
union of two thousand constants ran two thousand of their
__repr__methods for one refused value. Rendering stops at the bound, and a refusedvalidateon that union takes 0.03 ms rather than 0.5. - A wide record whose clause reads keys checks a JSON object in one pass.
is_valid_jsonagainst a record such as{"f0": int, ..., str: int}searched the document once per declared field, quadratic in the width: 580 ns a field at eight hundred fields against 70 at fifty. A record declaring more than eight fields resolves the document's keys through its plan, as a closed or an open record does, at about 40 ns a field whatever the width. - A complement's
expectednames the set it excludes. It named the kind of the schema it negates, socomplement(Literal["admin"])saidnot literalandcomplement(int | str)saidnot union, alone and as a union's branch. It readsnot the literal 'admin'andnot (int or str), naming its inner schema as a union names a branch. - Whether
openorclosekeeps a field turns on that field alone. A field saying what its record already says of every key it does not name is dropped, and the field was read as written to decide whether to drop any and as opened to decide which. So withVthe uniondict[anything, anything] | complement({}),{"b?": V, anything: anything}closed to{"b?": anything}, and with"c?": anythingbeside it to{}, though the two admit the same dicts; and{"b?": intersection({}, complement( dict[anything, anything]))}, which admits what{}admits, opened to a record refusing the keyb. A field is read once, as it stands with its own records opened: the first pair closes to{}, and the second opens todict[anything, anything]. - A missing key or attribute is spelled in
expectedasreprspells it. The label used Rust's escapes and double quotes, so a missing key"\x7f"readrequired key "\u{7f}"beside the path['\x7f'], and every such label was quoted unlike the path and the other labels. It readsrequired key 'a'andattribute 'x', as the path quotes the name.
Security¶
- A pattern over a base holding
bytesis a set of strings in the relations. The set representation readAnnotated[str | bytes, Regex("a*")]as the pattern's language overbytesas well, while the walk refuses every byte string. SoAnnotated[bytes, MaxLen(0)]was answeredsubsetof it, thoughb""is in the first and not the second;intersection(Literal[b"a"], complement(it))was answered empty, though it admitsb"a"; and its relation tostr, and toAnnotated[str, Regex("a*")], which it equals, wasnot_subset. The answers were wrong in 0.0.10 through 0.0.18. A pattern is read as its language overstrand nothing else, as the walk reads it, and a base holding no string meets it in nothing. A pattern over a base wider than the word kinds, such asstr | int, and a pattern no string matches, such as[^\s\S], are decided where they answeredundecided. - A value is walked once per definition where two branches read it as one.
recursive(lambda t: union(int, [t], [union(t, str)]))reads a list's element astunder both list branches, and each level of the value walked the level below once per branch, in every release through 0.0.18:validate_jsontook two seconds to refuse a document of 44 bytes on 0.0.17, and each further two levels multiplied it by four, on every entry point and for a value admitted by the second branch as well. The same held of a meet's members and of a map's clauses. A walk keeps what it answered for a definition at a value for the rest of the call, so the walk is linear in the value. A definition reaching a predicate, or a class whose metaclass is nottype, is walked at each occurrence as before, since that code is called at each one; the limits page says so. - A tuple reads what an unpacked tuple splices into it as written there.
tuple[int, *tuple[str, *tuple[bool, ...]]]was read astuple[int, str, tuple[bool, ...]], whose third element is a tuple, where both static checkers readtuple[int, str, *tuple[bool, ...]], so(1, "a", (True,))was admitted and(1, "a")refused, in 0.0.10 through 0.0.18; and a...inside a splice was the literalEllipsis. The spliced arguments are read as the tuple's own. A...after a splice,tuple[*tuple[int, str], ...], which repeated thestr, is refused, and so is an unpacked tuple outside a tuple's arguments:list[*tuple[int]]was a list of one-element tuples. - A
typealias of anAnnotatedalias in metadata is refused as the alias is.Annotated[int, Pos]withPos = Annotated[int, Gt(0)]is refused, since in metadata the alias annotates nothing, but the same alias writtentype Pos = Annotated[int, Gt(0)], or withTypeAliasType, was ignored and admitted-1in 0.0.17 and 0.0.18, whose refinements page refuses such an alias. An alias in metadata is read through to what it names, applied to arguments or not, and refused the same way. - A pattern
rereads as a different set is refused in two more forms. A+after a quantifier is possessive torefrom 3.11 and a second repetition here, soa?+admitted"aa", whichre.fullmatchrefuses; and this engine readsa{1, 3}, whitespace in its braces, as a count, whererereads it as the text"a{1, 3}", so it admitted"a". Every release through 0.0.18 read both forms so. Both raise aValueErrornaming the reading, as the class-set operators do. - A
Protocolmember declared withfunctools.cached_propertyholds what its function returns. It was read as a value, holding anything, so@cached_property def size(self) -> intadmitted an object whosesizeis a string, in 0.0.16 through 0.0.18; before 0.0.16 a protocol was the valuesisinstanceadmits, as its guide said. It is read as a property is, through its function's return annotation. closeafteropenrefuses again whatopenfreed, and no more. Opening folds the freed region into a clause admitting every value, and closing kept that clause whole wherever its key was not exactly the region:dict[C, Any]over a class,{int: Any, str: int}, anddict[int | str, Any]each round-tripped to a schema admitting every key, in 0.0.12 through 0.0.18, where the guide says the round trip is at mostclose. Closing takes out the region and keeps the keys the clause claims, so the first two round-trip exactly; where the complement law folds the opened key to every key, the round trip is a smaller schema thanclose. Anddict[Any, Any]relates todict[Literal["a", "b"], Any]opened assubset, where it answeredundecided.- A complement admits no member at the walk's bound. A union of scalars
that sat at the walk's depth bound, as a record's field or a mapping's value,
answered its scalar branches
falsewithout saying the walk had stopped, and a complement over the schema read that as the value being outside it:complement(recursive(lambda t: {"a?": {"x": {"y": t}}, "b": int | str}))admitted every value nested past the bound, in every release through 0.0.18, and from 0.0.10 a value the schema admits too. A scalar branch at the bound stops, as a scalar does anywhere else, and the complement refuses the value withrecursion_limit.
0.0.18 - 2026-10-12¶
A release with two breaks. Validator.simplify is removed, after warning
through eight releases, and a callable where a schema goes is refused, where it
was read as the constant it is. Two additions, one change, one removal and six
fixes.
A schema is built in the lattice normal form, so repr and == read the
reduction simplify promised, and the relations decide what it folded beyond
the laws. A callable where a schema goes is refused rather than read as a
constant, and the refusal names both spellings that were meant. Two readings
are new: a generic type alias applied to its arguments, and a meet with a
recursive reference, decided. Relations between maps decide where they
answered undecided: one is refuted on a key the other reads one way, and a
key written as a complement of kinds is read as the other kinds. The frontend
refuses an annotation at the node bound as it reads, in milliseconds where a
shared part built for over a minute; a validator built inside another build
counts only itself; deprecated and annotated_types.Unit in metadata are
ignored; and a product split across a wide union is held to the relation's
depth bound.
Added¶
- A meet with a recursive reference is decided. For
chain = recursive(lambda t: union(None, {"next": t})),intersection(chain, {"next": int})is empty andintersection(chain, {"next": {"next": None}})is not, where both answered"undecided". The reference is unfolded into the meet, a key that names it asks the meet of its types again, and a meet met again while it is decided reads as empty, under a goal of the meet's own rather than the reference's. A reference written inside a key's union,recursive(lambda t: {"next": union(t, None)}), decides the same way. - A generic type alias is read applied to its arguments.
Pair[int]fromtype Pair[T] = tuple[T, T]was refused as an unsupported form with originPair; it reads astuple[int, int], the body with the arguments in place of its parameters, for atyping_extensions.TypeAliasTypetoo. A parameter given no argument takes its default, and an alias whose every parameter has one reads bare. A recursive generic alias,type Tree[T] = T | list[Tree[T]], ties one fixpoint per list of arguments. A surplus or a missing argument, a bare alias whose parameter has no default, aParamSpecorTypeVarTupleparameter, and an alias applying itself to an argument that nests its own parameter each raiseNotImplementedErrorby the alias's name. A parameter's bound is a checker's to hold and is not read.
Changed¶
- A callable where a schema goes is refused.
Validator(fn),intersection(Record, fn),[fn],{"key": fn}andlist[fn]read a function, a bound method, apartialor a callable object as the constant it is, a set holding that one object -- so a meet meant to narrow a record by a check admitted nothing, and the decisions, which leave a meet with a literal undecided, could not say so. Each raisesNotImplementedErrornaming the two spellings that were meant:Annotated[T, fn]for the values ofTthe callable accepts, andLiteral[fn]for the object itself, which reads as the constant.Annotatedmetadata reads a callable as a predicate, as it did, and a class is read as the class it is.
Removed¶
Validator.simplify. It warned through eight releases, from 0.0.10. A schema is built in the lattice normal form, sorepralready shows the reduction it promised and==compares it; what it folded beyond the laws -- a meet of disjoint kinds, a join covering every region -- is a decision the relations make. Writeintersection(int, str).is_empty()rather thanrepr(intersection(int, str).simplify()) == "nothing", andunion(int, complement(bool), Validator(1)).is_equivalent(object)for a join that covers every value.
Fixed¶
- A validator built inside another build is measured on its own. An
annotation the frontend evaluates can construct a
Validator-- a predicate built in a field'sAnnotatedmetadata -- and that build started from the depth of the build around it, so a schema within the bounds was refused as nested too deep. Each build begun from the API counts only itself. The refusal past the depth bound names the bound it passed. - A map is refuted on a key the other reads one way. A relation between two
maps was left undecided wherever a refutation needed a key the subject's
clause admits:
{str: int}.open()against{str: int},dictand{str: bytes}against a recursive JSON schema,{tuple: int}against{str: int}, and{"a": str}against{str: int}.open()all answeredundecided, though{7: "x"},{7: 1},{"a": b""},{(): 1}and{"a": ""}refute them. The rules read a key schema by whole kinds -- one that holds every value of a kind, or none -- and refute where the supertype reads such a kind through one clause or none: an entry under a plain key of that kind is in the subject and outside the supertype. A key type whose plain values are unhashable, such aslist,tuple[list[int]]or a class whose instances are unhashable, holds a key only through a subclass that hashes, and is never refuted; two clauses reading one kind decline. A nesteddict[str, ...]is refuted at any depth, where five levels deep answeredundecided. - A map keyed by a complement of kinds is decided. A relation about a map
whose key was a
complement-- the clauseopenwrites on a mapping -- was left to the clause rules, and a pair they could not read answeredundecided: a plain class against{complement(str): int}or{str: int}.open(),dictagainst{str: Any, complement(str): Any}, and{complement(bool): int}against{complement(int): int, int: int}. The set representation reads a complement of whole kinds as the other kinds, a class instance among them -- so{complement(str): int}is outside the map keyed by every listed kind on{object(): 1}-- and atupleorfrozensetkey as its kind.Noneandboolkeep their finite keys:{None: int | str}opened is below{None: int}opened or{None: str}opened, and the same overboolis refuted on{True: 1, False: "x"}. A key holding part of a kind -- the complement of a literal,tuple[int, ...], a class -- declines, and the decidability page lists it. - An annotation is refused at the node bound as it is read.
Validator(spec)built the whole schema an annotation names before the node bound was asked, and a class, an alias or any annotation object is built once per place it is named -- so a part shared through several levels built a tree that multiplies with each. FourTypedDicts a level, each holding the union of the level below, took 75 seconds and 6 GB to be refused at twelve levels. The frontend holds what it has built to the bound as it reads and refuses a step past it, in milliseconds, with theValueErrorit raised before. A schema within the bound builds as it did; a part a fold drops still counts toward the union that dropped it. -
deprecatedandUnitin metadata are ignored.Annotated[int, typing_extensions.deprecated("...")]refused every value from Python 3.13, wheretyping_extensionsre-exports the standard library's decorator: its class lives inwarnings, which the frontend did not read as a typing form, so it was called as a predicate and raised.Annotated[float, annotated_types.Unit("m")]was refused as a constraint valgebra does not check, thoughUnitnames what a number is measured in and excludes no value. Both are ignored, as a typing form and the documentation marker are; a group yieldingUnitbeside a bound reads as the bound, andTimezoneis still refused. A decorator function in metadata, such asdataclasses.dataclassortyping.final, cannot be told from a predicate and is called, which the refinements page states. -
A product split across a wide union is held to the depth bound. A relation such as
tuple[int, int]against a union of hundreds oftuple[Literal[i], int]narrows the product by one branch a level, and those levels went uncounted by the bound that keeps a relation inside a 1 MiB thread, so a goal asked at the bottom of the chain could open its whole depth on top of them. Each branch is a level of that bound, and past it the relation answers"undecided".
0.0.17 - 2026-10-06¶
A correctness release: two additions, three changes and eighteen fixes.
Several answers change, each because the old one was wrong. Relations over
patterns and literals that were proved are refuted: a pattern's set is every
string it matches whole, and a literal is its constant at its exact type. A
value nested past 384 levels is refused where 512 were walked, so the walk
fits the 1 MiB stack the shipped wheels are measured on. A complement refuses
a value its inner walk stopped on rather than admitting it. A marker that is
not annotated_types' is ignored whole, a typing form in metadata is no
longer called as a predicate, and four forms that built quietly are refused. A
union of records told apart by a tag, and validate on a refused one, are
linear in the value. Two readings are new: instance_of(C), the instances of
a class whatever their fields hold, which a dataclass or a NamedTuple had no
spelling for; and a Final[T] field of a dataclass, read as T where the
class was refused.
Added¶
instance_of(C)is the instances of a class, and reads nothing it declares.Validator(C)checks each field of a dataclass or aNamedTuple;instance_of(C)admits every instance, an ill-typed or unset field included, which is the setisinstanceanswers. It is the class atom the algebra already held, with a spelling:Validator(C)is proved below it, and a dataclass whose declaration has no reading -- a bareFinalfield, a type parameter, a self-reference -- has this one. For a class that declares nothing it isValidator(C). ATypedDictand aProtocolhave no instances of their own and are refused, asisinstancerefuses them. The atom of a declaring class prints asinstance_of(C).- A
Final[T]field of a dataclass is a field holding aT. The typing spec makesx: Final[int]in a dataclass body a fieldxthat__init__sets and nothing assigns after, and a class carrying one was refused whole.Finalsays the name is not rebound, which is not a question about the value, so the field is read as the type it wraps. A bareFinal, whose type a checker infers from the default, is still refused.
Changed¶
- A union's report names the record branch that admitted the most. Of a
union's record branches, the one explained is the one whose check admitted
the most fields before refusing the value -- the fields decided by their own
value read first -- then one refused inside a field's nested value, the
earliest on a tie, where it was the earliest whose first failure lay
deepest. A value tagged for one record of a union is
reported against that record rather than against the first one:
{"t": "y", "z": 1.5}against{"t": Literal["x"], "z": int} | {"t": Literal["y"], "z": str}reportsz, not the tag. - The walk holds at most 384 levels open, from 512. The shipped wheels are
built with profile-guided optimization, whose frames are four to five times
the plain build's, and the deepest walk at 512 levels needed 1.5 MiB of
stack where the limits page promised 512 KiB. At 384 it needs under 896 KiB,
and the page says 1 MiB, the least stack any thread CPython creates has. The
smallest recursive body,
recursive(lambda t: union(int, [t])), is still walked to the unfolding bound of 128, so no answer for it changes; a deeper body meets the walk's bound sooner --{"a": {"b": {"c": T}}} | intis refused withrecursion_limitfrom 77 unfoldings, where it was 102. - A constraint is read off the
annotated_typesvocabulary alone. A marker carrying age, amin_length, apatternor afuncwas read by those names whichever library wrote it, and another library means its own thing by them: msgspec'sMeta(pattern="a+", max_length=3)became a whole-string pattern with its length dropped, where msgspec searches and keeps the length;Meta(ge=0)was refused for the pattern it leaves unset; pydantic'sAfterValidator(f)was called as a predicate and judged a value by the truth of whatfreturned. A marker whose class derives from the vocabulary is read for the vocabulary's names, apatternoffRegexand a compiledre.Pattern, afuncoffPredicate, and any other marker is its own library's metadata and is ignored, as pydantic and msgspec ignore each other's. AGroupedMetadatais unpacked before anything is read off it: pydantic'sStringConstraintscontributes its lengths, and its pattern, which pydantic searches with, is ignored. A class written bare is refused only where it is the vocabulary's own or a pattern marker's, and any other is ignored.
Fixed¶
- A pattern's set is every string it matches whole. The relations read a
Regexas the strings a search reports first, which is fewer than it matches: an alternation whose earlier branch is a prefix of a later one, an empty first branch, and a lazy repetition each lost the matches ranked below the first.Regex("http|https")was proved belowLiteral["http"]and equivalent to it,Regex("ab")was refuted belowRegex("a|ab"), and the meet ofRegex("foo|foobar")withLiteral["foobar"]was decided empty. Membership was right throughout: the walk matches a pattern whole, and the relations read the same set. - A field two clauses cover together is not refuted. A record field the
supertype does not name is read through the supertype's catch-all clauses,
and the field was refuted where each clause refused its type alone, though
the clauses together admit every value of it:
{"f": int | str}wasnot_subsetof{str: int, Any: str}, which holds it. Each clause's refusal stands on a value of its own; with two or more clauses the relation goes to the set representation, which decides this onesubset. - A set's refutation stands on members a Python set keeps apart. A set of
two element types is outside the union of the sets of each by a set holding
one member of each, and a Python set holds no two members that compare
equal. Where the two were one number in two kinds the refutation stood on no
value:
set[Literal[1, True]]wasnot_subsetofset[Literal[1]] | set[Literal[True]], though{1, True}is{1}and every set of it is in one of the two, and1with1.0read the same way. Those pairs areundecided; every other refutation of this shape stands. - A literal is its constant at its exact type. The relations read
Literal[5]as everyintequal to 5, anintsubclass's included, where the walk admits the exactintalone:Annotated[int, Ge(5), Le(5)]was proved equivalent toLiteral[5],Annotated[str, Regex("a")]belowLiteral["a"], and the meet ofLiteral[5]with anintsubclass was not proved empty. AnIntEnummember equal to 5 is in the bound and not in the literal, and those pairs are refuted or decided the other way. Membership was right throughout. - A record is not proved below a mapping keyed by literals.
{"a": int}wassubsetofdict[Literal["a"], int], and{MyStr("a"): 1}is in the record and not in the mapping: a field reads every key equal to its name, and a literal key is the exactstr. A proof that stands on a literal key subtracted from a dict a field or a kind's part can key isundecided; a subject keyed by literals alone decides, and every refutation stands. - A complement refuses a value its inner walk stopped on. A walk that
stops -- past the depth bound, at a value that contains itself, at a value
that changes while it is read, at a predicate that raises -- answers no as a
non-member does, and
complementadmitted every such value:[T] & ~T, which the relations prove empty forT = recursive(lambda t: [t]), admitted a list one level past the bound throughis_valid,validate,ensure,is_valid_jsonandload, and so did the documented deny-list shapeintersection(X, complement(P))for a predicate with a bug. The complement refuses the value with the code the inner walk stopped with. is_validandvalidateagree at the depth bound. A union of literals is answered from a table when a value is only being checked and branch by branch when it is explained, and the table answered without the level a branch takes: a value whose union of literals sat one level past the bound was a member tois_validandinand refused withrecursion_limitbyvalidateandensure. Both refuse it.- A union of records told apart by a tag is linear in the value. Fields are
read sorted by name, so a tag such as
typebeside a recursiveleftwas read after the child, and each branch the tag refused walked the whole child first:is_validon a valid value of four such branches took a second at ten levels and did not return at twenty, on the object and the JSON path alike. The check reads a field decided by its own value first. validateon a refused union of records is linear in the value. Each refused record branch was explained in full, its recursive field included, so the default report on a refused chain of such a union doubled per level: a third of a second at eighteen levels of a three-hundred-byte value. One record branch is explained.- A union runs no
__repr__of a value it admits. A branch before the one that matched was explained -- a named tuple, a list, a set, a tuple, a meet or a complement -- and explaining it rendered the value: a__repr__that raisedMemoryErrormadevalidateraise for a member, and a 20,000-element member oflist[int] | list[Slow]ran 20,000 of them. 0.0.16 settled this for record and class branches; the union is decided before any branch is explained. - A relation does not overflow the stack. Two recursive schemas whose
bodies nest 100 and 99 lists around the back edge, or a chain of 96
definitions each a hundred one-tuples deep, made
relation_to,is_subtype_of,is_equivalentandis_emptyrecurse until the process died, on the main thread as on any other: the work budget counts steps, and each level is a few of them. A relation holds at most 512 levels of its own recursion and answers undecided past them. - A JSON object's keys cannot be chosen to collide. The undeclared keys of
a parsed object wider than eight entries were collected into a table hashed
with an unseeded hash, whose collisions are the same in every process: a
document of 20,000 keys computed to collide, 0.74 MB, took half a second
against
dict[str, int]where as many ordinary keys took 2 ms, four times as long for each doubling. The table is keyed per process, and the keys are covered in the document's order. An ordinary wide object reads 9% to 14% fewer instructions than before. - A qualifier inside
Annotatedsays whether aTypedDictkey is required.Annotated[NotRequired[int], Ge(0)]was read from the class's key sets, which underfrom __future__ import annotationsCPython computes from strings: the key was required, andAnnotated[Required[int], Ge(0)]in atotal=Falseclass optional. - A typing form is refused where a constant or a type argument is read.
Literal[list[int]]builtlist[int],Literal[NewType("U", int)]builtint, and on 3.10Literal[Any]builtAny;NewType("N", "int")andTypeAliasType("A", "int")built the literal'int';InitVar[int]built a literal of the form object; and below 3.13 a bareAnnotatedbuilt a class test no value passes. Each is refused, naming the spelling that was meant. \<,\>and\b{...}are refused in a pattern. They are word-boundary assertions in this engine and literal characters tore, soRegex(r"\<b\>")admitted"b"and refused"<b>".- A union holding a record prints as the call that builds it.
union({'a': int}, {'b': str})printed as{'a': int} | {'b': str}, which Python reads as a dict merge, the one record{'a': int, 'b': str}, and a union beside a list display printed an expression that raisesTypeError. Both print asunion(...). A record's key is spelled by Python's ownrepr, where a name carrying a quote printed as two fields. openandclosereach the record a mapping maps to.dict[str, {'b': int}]opened freed the key-types besidestrand left the record everystrkey maps to closed; that record is opened with the rest, and closed with it. The pages calledclosea function of the set, and it rewrites the term asopendoes: a meet of two open records and the open record of their fields are one set, and the meet closes to nothing. The pages say so now, and that a secondopengives the set the first did and may respell it.- A typing form in metadata is not a predicate. A callable in
Annotatedmetadata is a predicate, and every typing form is callable: calling one with a value built something, and its truth was the verdict.Annotated[float, at.IsFinite[float]]admitted infinity and refused zero,Annotated[str, list[int]]refused the empty string, and a bareat.IsFiniteraised for every value. A typing form is metadata this frontend does not recognize, and is ignored; anAnnotatedalias carrying a marker this frontend reads is refused, naming the spelling that was meant.
0.0.16 - 2026-10-04¶
A protocol and correctness release: three entries, one change and two fixes.
A Protocol is the record of the members it declares, decorated or not, where
it was an isinstance check that held only where @runtime_checkable sat on
the class itself, and it relates to other schemas as a record. Six things a
runtime-checkable protocol did break, and the entry below names each. A
refutation about a class stands on an instance that can carry its fields, so a
pair refuted on a value that may not exist is undecided. And validate
explains a union's record and class branches only for a value the union
refuses, so a member of such a union is checked without running any
__repr__.
Beside the entries, the release carries performance work on validating a value, on building a validator and on relations between validators. No answer changes.
Changed¶
- A
Protocolis the record of the members it declares, decorated or not. A protocol compiled to anisinstancecheck against the class, and only where@runtime_checkablewas applied to the class itself; any other protocol was refused. It denotes the values carrying every member it declares, each read bygetattr: an annotated member holds a value of its type, a method or special method holds a callable, and a property holds what its getter's return annotation names.
Six things a runtime-checkable protocol did break. A member present with a
value outside its type is refused, where isinstance admitted it. An
instance of a class naming the protocol among its bases, with a data member
never assigned, is refused. A member a __getattr__ hook serves, a getter
that raises and an unassigned slot answer alike on every release, where
isinstance answered them one way on 3.10 and 3.11 and the other way from
3.12. A generic runtime-checkable protocol -- typing.SupportsAbs and
typing.SupportsRound among them -- and one declaring a member ClassVar or
Final built in 0.0.15 and are refused now, each with the reason. A value
refused reports the member it lacks or holds wrongly: missing_attribute at
the member's path, expecting attribute "__int__", where it was
instance_type at the root expecting the protocol's name, so a caller
branching on the code reads another one. And repr prints the record of the
members, object(x=int), where it printed the protocol's name. A protocol
without the decorator, or inheriting its mark from a base, builds where it
was refused, and the bare Protocol base is refused, with the reason.
A protocol relates as a record: a dataclass declaring its members, each at
least as narrowly, is below it, and a protocol with more members is below one
with fewer. A record is not read as satisfied by an exact int, str or
other builtin value, whose attributes are its type's, so a builtin kind
against a protocol declines where the witness would be such a value.
Fixed¶
- A relation about a class and its fields stands on an instance that can
carry them. A dataclass is its class met with a record of its fields, and a
refutation about one --
not_subsetagainst a kind or another class -- stands on a direct instance of the class holding a value in each field. That instance was assumed whatever the class defines. Where a field's name is a property or another data descriptor on the class, or the class defines__getattribute__, what the instance holds there is the answer of code, and the pair was refuted on a value that may not exist; it isundecided. A class whose instances have no__dict__, a name the class body defines and a slot are read the same way, each for what a direct instance can hold. validateexplains a union's record and class branches only for a value the union refuses. A record branch -- aTypedDict, a dict schema, a mapping -- and a class branch, a dataclass among them, were explained as each was decided, and the report was dropped when a later branch admitted the value:validateran the value's__repr__, or a field's, once for each such branch before the one that matched, a predicate under one ran a second time, and a repr raisingMemoryErrormade it raise for a member. A record branch's explaining pass waits until no branch has admitted the value, and a class branch is decided by its instance test, a dataclass's where its metaclass istype.validateon a member of a union of records or of dataclasses costs a fifth of the instructions it cost, close to whatis_validcosts; the report for a value no branch admits is unchanged.
0.0.15 - 2026-10-01¶
A correctness release: thirty-three entries, all fixes.
Four relations answered wrongly and two declined. A step of -2**63 was read
as the set holding zero, a pair of float bounds as reals with a real between
them, a step dividing another as an inclusion across kinds of number % does
not keep, and one dict key as witnessing two clauses of a union. A record below
the complement of two records, and a union of pattern refinements below the
complement of an empty one, are decided where they were undecided.
The frontend reads more of what the typing spec writes. A validator in
Annotated metadata narrows the schema rather than being ignored, a
typing_extensions form reads as its typing one, and a TypedDict built by
typing_extensions or inheriting from a closed one admits the extra keys its
declaration says. A marker class written without its parentheses, a bare
TypedDict or NamedTuple, a pattern that parses only once anchored and a
space or # in a verbose character class are refused, where each built a
schema for another set or failed for another reason.
A fatal signal -- an interrupt or a MemoryError -- raised in code the library
calls propagates from every site that read it as an ordinary answer: a key's
__eq__, a type's metaclass, the __repr__ of any part of a message, a
predicate, bound or step that building or a relation asks, and the comparison,
hash and repr of a constant a validator holds.
Three fixes are about a process rather than an answer. Building the first
validator on Python 3.15 could wait for good beside a thread importing
annotationlib, and on PyPy a tuple subclass yielding fewer items than it
holds crashed validate, and a dict whose key a predicate swapped mid-scan
took the interpreter down.
The rest are the walk and its reports. A list subclass is judged by what it
holds on every interpreter, as a tuple or dict subclass is on PyPy, and a
length bound is read before the elements it bounds. A report names an
intersection branch by its members, quotes a key that is not a bare name in
its location, spells a pattern as its Python literal, names each key of a path
by what it holds, and under fail_fast walks each union branch only to its
first failure.
Fixed¶
- A
TypedDictbuilt bytyping_extensionsis open unless it says otherwise. PEP 728 writes "noextra_itemsgiven" with a sentinel, andtyping_extensionscarries its own, a different object fromtyping's before Python 3.15. On 3.10 to 3.14 its open default, andclosed=False, were read as a record whose only admitted extra value was that sentinel, so every extra key the class allows was refused. And on every releaseextra_items=None, which gives the extra values the typeNone, was read as no marker and admitted any extra value. Each spelling is read as it says, whichever implementation built the class. - A validator in
Annotatedmetadata narrows the schema.Annotated[int, v]for a compiled validatorvwas read asint: the validator was taken for metadata nothing recognizes and ignored, so a class field written to refuse whatvrefuses admitted everyint. It is the meet of the refined base andv, the setintersection(int, v)builds, whether the validator is written on its own, beside other markers or inside a grouped one; a static checker reads the field asint. - A union's report names an intersection branch by what it admits. The
branch was listed as the word
intersection, which names no set; it lists each member joined withand, as inone of: str, int and not bool, with a member that is itself a union in parentheses. - Refusing a union under
fail_fastcosts a fail-fast walk of each branch. The report chose the closest branch by the deepest failure anywhere in it, which walked every branch whole even underfail_fast: a 100,000-element list refused inside a union branch took 350 ms whereis_validtook none. The closest branch is the one whose first failure lies deepest, which a walk stopped there has measured, so underfail_fasteach branch stops at its first failure, and the full report chooses the same branch. Where one branch fails shallowly and again deeper inside, the other branch may be the one reported. - A fatal signal raised by a key's
__eq__or a type's metaclass propagates. An interrupt or aMemoryErrorraised while the walk looked a record's field up by name, resolved astrsubclass key to a field, asked a tuple or set subclass's type for its__len__or__iter__, copied a value through its storage or turned a JSON value into a Python object was read as a failed probe, so the check answered and the signal was lost. Each is re-raised, as one raised by a predicate is. - A list subclass is judged by what it holds on every interpreter. Below
Python 3.14, and on free-threaded builds, a list of scalars was read through a
copy that iterates it, so a subclass whose
__iter__yields something other than what it holds was judged by what it yields there and by what it holds on 3.14. Only an exact list is copied. - A marker class is refused with the spelling that was meant.
Annotated[int, at.Ge], a marker written without its parentheses, was ignored as unrecognized metadata, so the schema wasintand admitted every value the bound was written to exclude. A class whose instances would be read or refused as a constraint -- one fromannotated_types, or one carrying a name a constraint is read through, such asgeorpattern-- is refused with a message namingGe(...). Any other class, such as a unit or an enumeration, is ignored as before. - A length bound is read before the elements it bounds.
Annotated[list[int], MaxLen(3)]walked every element of a longer list before reading its length, so a list of a million elements cost a million checks to refuse, and one holding a wrong element was reported for the element. On a list, tuple, set, frozenset or dict,MinLenandMaxLenare read once the value is of the base's kind and before any element, where a fixed shape reads its length: the list is refused withtoo_longalone. Membership is unchanged. - An opened map lists its clauses as the same clauses written out do.
open()folds the key region no clause claims into the clause carrying the same value, and kept that clause where it stood, soValidator({int: object, str: int}).open()rendered its clauses in another order than the same clauses written out, though the two compare equal. The opened list takes the order every spelling of it gets. - A step of
-2**63is not read as zero alone.Annotated[int, MultipleOf(-2**63)]admits-2**63and2**63, and its steps were read as the set{0}, so it was proved belowAnnotated[int, Ge(0)]and proved empty besideGt(0). The step's magnitude is past the integer set's period, as every step that large is, and a relation that turns on it declines. - No float lies between a float and the next one. A set of floats was read
as a set of reals, so
Annotated[float, Gt(1.0)]andAnnotated[float, Ge(math.nextafter(1.0, math.inf))]were proved to differ though they admit the same floats, and a pair of bounds with no float between them was read as inhabited. An open bound is held as the closed one at its neighboring float, and both relations are decided exactly. - A step dividing another is not read across kinds of number.
Annotated[int, MultipleOf(6.0)]was proved belowAnnotated[int, MultipleOf(3)]because3divides6.0, and2**53 + 5is in the first alone:%reads theintas the float nearest it. A step past2**53overfloat, and aDecimalorobjectbase, met the same proof and the same counterexamples. The inclusion is proved where%reads a value and both steps as one kind of number, and declines elsewhere. Anintstep against afloatstep overfloatis decided, by the operator's reflected form. - One dict key cannot witness two clauses of a union. The closed record
{"a": int | str}was reportednot_subsetof{str: ~int} | {str: ~str}, though{"a": 1}is in the second and{"a": "x"}in the first. Each "some key maps into this" constraint of a map was read on its own, so two of them found the one keyaand asked it for anintand astrat once. The constraints no fresh key can meet are read together, and so are the two keys ofbooland the one ofNone, which a constraint can run out of. - A pattern that parses only once anchored is refused.
Regex("a)|(b")does not parse, and wrapped for a whole-string match it closes the anchors' group and opens one they close, so it compiled into an alternation that escaped both anchors and admitted"xxb". A pattern is parsed on its own before it is anchored, and one that does not parse raises the build'sinvalid regular expressionerror. - A fatal signal from any part of a message propagates. A
KeyboardInterruptfrom the__repr__of the constant a literal names, of a bound or step a value missed, of a value a constraint refused, of a key the path names by its repr, or from a metaclass answering__name__, read as<unrepresentable>in aValidationError. The value refused by its kind was the one site that carried it out. Every part of a message the walk renders raises the signal out ofvalidate. - An object carrying
__metadata__and no__origin__is a value. The build read any object with__metadata__asAnnotatedand asked it for__origin__, so an object without one failed with a bareAttributeError, a type the build is documented never to raise. It is read as every other object is, as the literal of itself. - A
typing_extensionsspelling reads as itstypingone. Before the release that adds a form totyping,typing_extensionsdefines it with an object of its own, and the frontend askedtypingalone. On 3.10typing_extensions.Neverread as a literal of the form object and admitted it,Anyread as a class nothing is an instance of,SelfandLiteralStringread as literals, andRequired,NotRequired,ReadOnlyandUnpackwere refused, so aTypedDictusing them did not build. Before 3.15 an alias built withtyping_extensions.TypeAliasTyperead as a literal of the alias. Each reads as itstypingspelling does. - A bare
TypedDictorNamedTupleis refused. Each is a function or a form at runtime, andValidator(NamedTuple)read it as a literal of that one object, a schema that admitted nothing a caller has. A checker readsNamedTupleas every named tuple class and refusesTypedDictas a type. Both, fromtypingortyping_extensions, raiseNotImplementedErrornaming the class to pass instead. - A
TypedDictsubclass inherits what its base says about unnamed keys. The typing spec's open default holds "except when inheriting from another TypedDict that is not open", and the runtime writesclosedandextra_itemsonly on the class that gave them. A subclass of aclosed=Trueorextra_items=TTypedDictread as open and admitted any extra key. It reads what its nearest base states, and a class that saysclosed=Falseitself stays open. - A space or a
#inside a character class under verbose mode is refused.re.VERBOSEkeeps both as members there, and this engine ignores the space and starts a comment at the#.re.compile("[ a]", re.VERBOSE)as a marker admitted no space wherereadmits one, and[#a]failed with "unclosed character class". Underre.VERBOSE,(?x)or(?x:...), either character in a class raises aValueErrornaming it and the escape to write instead. - The unsupported-form refusal names every subscripted form it reads. It
ended "supported: list, set, dict, tuple, Union, Optional, Literal,
Callable", which left out
frozenset,Annotatedand theTypedDictqualifiers, all of which build. The list names each of them. - A
tupleordictsubclass is read for what it holds on PyPy. PyPy's C API reads a subclass through the methods it overrides. Atuplesubclass whose__iter__yields fewer items than it holds crashedvalidateandensure, andis_validanswered about items it does not hold; adictsubclass overriding__len__was refused by a closed record it belongs to, and one overriding__getitem__bydict[str, int]. Such a value is copied through the base type's own methods and the copy is walked, which reads what CPython read all along. - An error path names each key by what it holds. A big integer key was
spelled by its own
__str__, so anintsubclass answering"7"named another key, and one raisingKeyboardInterruptlost the signal and was spelled as a string. Its digits are read from its storage, as a small integer's value is. Astrkey holding a lone surrogate read as the empty string and named the entryd[""]is; it appears as itsrepr, like any key a path cannot spell. - A signal an element's
__repr__raises once propagates from a summary. A container is summarized throughreprlib, which lets aKeyboardInterruptthrough; the plainreprbehind it then ran the element again and read its answer as the summary, so a signal delivered once, as an interrupt is, became aValidationError. - Building a validator and asking a relation carry a fatal signal out. A
relation runs user code -- a predicate or an
__eq__it probes a literal with, a bound's comparison -- and read a fatal signal raised there asundecided, asFalsefromis_empty, or, through a literal, as the verdictnot_subset. Building read one raised by a marker's attributes, a bound's conversion or a step's comparison with zero as the fallback an ordinary exception gets, and an interruptedisinstance(bound, Number)as a bound with no order, refused with aNotImplementedErrorabout the wrong cause. Each raises the signal. validateexplains no union branch that refuses a value by its kind. Such a branch fails at the union's own location, where a report reads only the union's label, and explaining it summarized the value:validateran a member's__repr__once for each branch before the one that matched, and a repr raisingMemoryErrormade it raise for a member. The branch is decided without being explained; the report for a value no branch admits is unchanged.- A dict whose key is swapped mid-scan is answered on PyPy. A predicate or a
key hook replacing one key with another at the same size, while
dict[str, T]or a record withextra_itemsscanned the dict, made PyPy's C API fail fatally and took the process down. The scan reads a copy there, and the change is the one the walk does not see, as on CPython. - A key that is not a bare name is quoted in a message's location. The
location wrote every string key as itself, so the key
"a.b"read as the pathathenb,"[0]"as the index 0 and the empty key as nothing, and a key holding a newline splitmessage, and its line ofstr(exc), in two. Such a key is written as a subscript of its Python literal,at ['a.b']:; the structuredpathis unchanged. - A pattern's and a depth bound's
expectedname the set a value missed. A pattern was spelled in Rust's escaping,a string matching "\\d+", beside labels spelling a constant as Python'srepr; it is the pattern's Python literal,a string matching '\\d+'. The depth bounds readat most 512 levels of nesting, got [[...]], which reads the value as a count; they area value at most 512 levels deepanda value at most 128 recursive levels deep. - A record below the complement of two records is decided.
{"t": int}againstcomplement({"t": str} | {"t": bytes})answeredundecided, where a union of one record or of three decided: the set representation took the complement of the complement, and where a field spanned two kinds that rebuilt set cost more than a relation may spend. It meets the record with the union itself. ==,hash,reprand a build refusal carry a fatal signal out. A constant whose__eq__,__hash__or__repr__raisedKeyboardInterruptread as unequal, as adding nothing to the hash and as<unrepresentable>. A length bound whose__index__raised one was refused as no length, and a refusal naming an object whose__repr__raised one named it<unrepresentable>. Each raises the signal; an ordinary exception reads as before.- The complement of an empty refinement is above every subject.
complement(Annotated[str, Regex("x"), MaxLen(0)])is the universe, since no string both matchesxand has no characters, yet a union of forty pattern refinements answeredundecidedbelow it: the set representation read the pattern only by lowering the subject too, and that union is past what it lowers. The complement rule asks the refinement's own emptiness where disjointness declines. - Building the first validator does not hang beside an import on Python
3.15. There
typingreachesannotationlibthrough a lazy import, and resolving one holds the interpreter's global import lock while it waits for the module. The first build readtyping.ForwardRefthat way, so a thread importingannotationlibat that moment --dataclassesandinspectboth do -- and the build waited on each other for good. The build importsannotationlibitself first, where the release has it.
0.0.14 - 2026-09-26¶
A typing and correctness release: five entries, two additions and three fixes.
A static checker reads a validator's set: Validator[T] is generic, a True
from is_valid narrows to the type on a typed validator, and ensure and
load return it. Two classes whose own __slots__ lay down layouts share no
instance, so their meet is decided empty as a meet of two builtin subclasses
is, and a slotted class over no builtin is below the complement of every
builtin kind.
Three fixes. A protocol is a schema only where @runtime_checkable was
applied to it, since a class that inherits the decorator answers isinstance
with a warning from 3.15 and a refusal from 3.20, and under -W error was
read as admitting nothing. The PyPy wheels are plain release builds: the
profiled ones 0.0.12 and 0.0.13 carry die with a segmentation fault at the
walk's depth bound. And there is a wheel for PyPy 8.0 beside the one for 7.3,
since 8.0 changed the ABI tag and a wheel for one does not install on the
other; the release runs the whole product suite on each PyPy wheel it ships.
Added¶
- A static checker reads a validator's set.
Validator[T]is generic in the type a checker reads for its schema:Validator(int)is aValidator[int], a dataclass orTypedDictclass names its own type, a compiled validator keeps its own, and a native form, aLiteral, anAnnotatedrefinement or a combinator reads asValidator[object]. On a typed validator aTruefromis_validnarrows its argument to the type, andensureandloadreturn it; on an untyped one the answer stays aboolandensurereturns its argument's own type. The narrowing is aTypeGuardand not aTypeIs, because aFalseproves nothing a checker can use: this library'sfloatrefuses theinta checker admits there. A bareValidatorannotation isValidator[Any]and takes every validator; the parameter is invariant, so aValidator[object]parameter takes only an untyped one.Validator[int]is atypes.GenericAliasat runtime, and handed back as a schema it is refused by name.simplifyis marked deprecated where a checker sees it, beside the warning it raises at runtime. ty, mypy and pyright read the stub alike. - Two classes laying down slots of their own share no instance. A class
whose
__slots__add a slot lays down an instance layout, as a class built on a builtin does, and Python refuses a class deriving from two layouts unless one extends the other.intersection(C, D).is_empty()isTruefor two such classes neither of which derives from the other,Validator(C)is belowcomplement(D), and a slotted class over no builtin is below the complement of every builtin kind. A plain subclass of a slotted class still meets a slotted subclass of the same base, in the class Python builds from both. An empty__slots__, or one naming only__dict__and__weakref__, lays down nothing; the@disjoint_basedecorator of PEP 800 is not read, since the runtime does not enforce it.
Fixed¶
- The PyPy wheels no longer crash at the walk's depth bound. The released
PyPy wheels were profile-guided builds like the CPython ones, and on a value
nested to the depth bound a profiled extension ran out of the native stack
budget PyPy's C-API layer sizes from the recursion limit before the walk
reported
recursion_limit; the process died with a segmentation fault. The PyPy wheels are plain release builds, which report the bound, and the release smoke runs the whole product suite on each PyPy wheel it ships rather than importing it alone. - A wheel for PyPy 8.0. PyPy 8.0 changed the ABI tag from
pp73topp80, and an installer matches the tag exactly, so thepp73wheels every earlier release built install on PyPy 7.3 and not on 8.0. The release builds a wheel for each on manylinux x86_64 and aarch64, and smokes each on the PyPy it is built for. - A protocol is a schema only where
@runtime_checkablewas applied to it. A subclass protocol inherits the attribute the decorator sets without the decorator, and was read as theisinstancecheck its base allows. Python 3.15 warns on everyisinstanceagainst such a class and 3.20 refuses it, and the walk reads a warning raised as an error as a non-member, so under-W erroron 3.15 the schema admitted nothing and said nothing. It is refused on every release, naming the class and the decorator to add; decorated itself, the same class is read as before.
0.0.13 - 2026-09-24¶
A support and correctness release: ten entries, one addition and nine fixes.
Python 3.15 is supported, and every platform a wheel ships for but musllinux gets one for every interpreter the classifiers name: 0.0.12 left Apple silicon without 3.10 and every platform but Linux without free-threaded 3.14.
Two fixes are about a process rather than an answer. A recursive meet of
records overflowed the native stack from is_empty() and is_subtype_of() and
ended the interpreter, and two threads reaching a validator's first call
together could stop each other on a free-threaded build.
The decision procedure decides more, and one wrong answer goes. A fixed-length
sequence of unions against the union of its corners, a fixpoint's unfolding
below the fixpoint, and a union of complements that covers every value are
decided where they were undecided; a literal-keyed clause is read as the clause
it is, where it refuted an inclusion no value refutes. On 3.15 a frozendict
literal is refused as a frozenset literal is, rather than read as a constant.
Added¶
- Python 3.15 is supported. The package names it in its classifiers, every
push runs the suite on 3.15 as a merge gate, and a release ships
cp315and free-threadedcp315twheels for manylinux, macOS and Windows x64, andcp315for Windows arm64. Until 3.15.0 is published the wheels build against its release candidate, whose ABI the final release keeps. 3.10 stays the floor.
Fixed¶
-
Every platform gets a wheel for every interpreter the classifiers name. 0.0.12 shipped no
cp310wheel for Apple silicon and no free-threaded 3.14 wheel off Linux, though its classifiers name 3.10 and stable free threading: the macOS and Windows builds ran on the host and built for the interpreters the image carried. The release installs 3.10 through 3.14 and 3.14t there first, and Windows builds its free-threaded wheel in a job of its own. The smoke imports each wheel set on the floor, the newest release and the free-threaded build, and the free-threaded import must leave the GIL off. Windows arm64 keeps 3.12 and later, which its image carries. -
Threads that reach a validator's first call together wait detached. The first call builds the validator's indexes, and a second thread arriving during the build waited attached to the interpreter. On a free-threaded build the builder interns strings, which can wait on a lock and let a stop-the-world pause begin that an attached waiter never reaches, and both threads stop. The waiter detaches, which is the wait PyO3 provides for this shape; the hang is reasoned from that contract rather than reproduced.
-
A recursive meet of records is decided rather than overflowing the stack.
is_empty()andis_subtype_of(int)onValidator(recursive(lambda t: intersection({"a": union(t, int)}, {"a": union(t, str)})))overflowed the native stack and ended the process; both answer. Emptiness of a meet of records asks the meet of the types a required key carries, and it read that meet with a fresh cycle check, so each unfolding of the fixpoint reached the same meet again. The meet is read under the cycle check of the node it belongs to, as a field of a single record is. -
A fixed-length sequence of unions is decided against the union of its corners.
Validator(tuple[K, K]).relation_to(union(*(tuple[a, b] for a, b in product(K, K))))forK = int | str | bytes | float | Noneanswered"undecided"and answers"subset", in a few milliseconds; with one corner left out it answered"undecided"and answers"not_subset". The product rule narrowed by every branch at every position and ran out of its work budget; it drops a branch that shares no value with what is left, which is exact, and it refutes where every union member it sets aside holds none of the subject's values. A widening: no answer that was a proof or a refutation changes. -
A
frozendictliteral is refused rather than read as a constant. On Python 3.15,Validator(frozendict(a=int))builtLiteral[frozendict({'a': <class 'int'>})], a schema admitting that one mapping and refusingfrozendict(a=1)and{"a": 1}: afrozendictis not adict, so it missed the dict literal's arm and fell to the constant reading. It raisesNotImplementedErrornaming the dict literal anddict[K, V], as afrozensetliteral does.frozendict[K, V]stays refused, and afrozendictvalue is admitted bycollections.abc.Mappingand not bydict[K, V]or a record. -
A relation between a builtin kind and a class with declared attributes is decided. The published decidability boundary listed an attribute record on either side as a conservative case, and
int ≤ CandC ≤ intas "not proven" for a class with declared attributes. Both are refuted, with a value that decides each. A declared attribute is not a source of conservatism: the same relation declines for a class with no fields and decides for a class laid out as a kind, so the declines beside such a class are the open class order's, which the page assumes elsewhere. Thirty-two ordered pairs of schema nodes move from "not proven" to decided in the page's account. No answer the library gives changes; what changes is the account of it, and the ledger behind it, which drove aProtocolwhere it said it drove a record. -
A fixpoint's unfolding is decided below the fixpoint however its body is spelled.
Validator(union(m, list[t])).relation_to(t)fort = recursive(lambda x: union(m, list[x]))andm = intersection(int, union(float, bool))answered"undecided"and answers"subset". A meet on the left of a reference was placed only where a member of the meet was below the reference, and where none was the pair ended undecided without the reference being unfolded; every other subject reached the unfolding. The meet rule runs first as before, and a meet it does not place is asked against the definition the reference names, as a union member always was. A widening: no answer that was a proof or a refutation changes. -
A literal-keyed clause is a clause, and a relation reads it as one.
Validator({"k?": str | int, str: int}).relation_to({Literal["k"]: str, str: int})answered"not_subset"and answers"subset"; the two are one set, andis_equivalentsays so. The walk reads a literal-keyed clause as the page states -- a key belongs when some clause admits it and its value, so{"k": 1}is a member through thestrclause -- and the set representation read it as a field, which takes precedence, so it refuted an inclusion no value refutes. The lowering joins the clause's type with every clause that covers the key; a field of the same name is read instead of them, as before. -
A union of complements whose inners share no value is the universe, and every subject is below it.
Validator(complement(Annotated[int, pred])) .relation_to(union(complement(None), complement(set))), for a predicatepred, answered"undecided"and answers"subset": no value is bothNoneand a set, so the union holds every value. The universe bound read a union's members by their regions and passed over the one the partition cannot read, which here is the member covering what the other leaves out. Where every rule declines, the union is now also read one De Morgan step in, as the meet of its members' complements, whose emptiness the rules decide. A widening: no answer that was a proof or a refutation changes.
0.0.12 - 2026-09-19¶
A correctness release: thirty entries, and twenty-nine of them are fixes.
The decision procedure decides more. A record whose fields each take several types is the union of the records that fix them; a subject sharing no value with any branch of a union is outside the union rather than undecided; a branch the subject cannot meet is dropped before the rest is asked; and divisibility between two moduli is settled by the steps themselves, which is the one addition.
The frontend refuses what it cannot build, rather than building a schema that denotes the wrong set. Four annotation forms, a frozen set literal, a character class carrying an operator the engine reads differently, an arity, and an order bound whose base and bound do not compare: each raised nothing and admitted the wrong values, and each is a refusal naming what it is about.
The walk says what it found. A union summary names its branches and keeps what stopped the walk, a report keeps the promises the error model makes, a refutation stands on a value, and a render that gave up says so.
Behind several of them is the descriptor's own reading of a kind: a string kind
holds the characters no pattern matches, a set is at most as long as the values
its element denotes, a dict has one entry for 1 and for True, and an
integer bound at the end of the carrier keeps the integers past it. Each was a
set the representation named wrongly, so each was a relation answered wrongly.
Added¶
- Divisibility between two moduli is decided by the steps themselves.
Validator(Annotated[int, MultipleOf(5000)]).is_subtype_of(Annotated[int, MultipleOf(2500)])wasFalseand isTrue. Every multiple ofais a multiple ofbexactly whenbdividesa, so the two steps settle the inclusion between them and the size of either is beside the point; the question is%, asked of the steps, so a divisor of any numeric type answers by its own rules. The refutation and the meet still want the residue representation, and the decidability page says which is which.
Fixed¶
-
A subject outside every branch of a union is refuted, not left open.
Validator({"a": chain, "b": int}).relation_to(union({"a": chain}, {"a": chain, "b": str}))answered"undecided"and answers"not_subset". A subject sharing no value with any branch is outside the union, so where it holds a value that value refutes the inclusion; reading the case as "proved, or not proven" kept the proof for an empty subject and dropped the refutation for every other. -
A union branch sharing no value with the subject decides nothing.
Validator(chain).relation_to(union(None, {"next": int}))answered"undecided"and answers"not_subset", naming the link the supertype refuses. A branch the subject cannot meet is dropped before the rest is asked, so an inclusion refuted by one branch is refuted rather than left open: the rules refute against a single supertype and have no arm that refutes against a union. -
An order bound is refused where the base and the bound do not compare.
Validator(Annotated[None, Ge(0)]), and the same over adictor aset, built a schema that admitted no value at all and reported itself inhabited; each raisesNotImplementedErrornaming the order the base cannot be asked. A bound is a question about two values, so the kind of the bound decides the answer with the kind of the base:Annotated[set[int], Ge(0)]is refused andAnnotated[set[int], Ge({1})]admits the supersets of{1}. A list, a tuple and a set take a bound of their own kind, which they already ordered against. -
A record is decided against the union of records it splits across.
Validator({"a": int | str, "b": int | str}).is_subtype_of(...)over the four records that fix both keys wasFalseand isTrue, andrelation_toanswers"subset"where it answered"undecided". The four records are that record, the way a fixed-length tuple is the union of the tuples it splits across.The same reading settles a difference written as one complemented union.
a & ~(b | c)anda & ~b & ~care one set, and both are decided where either is: a meet against a complemented union removes one part at a time rather than expanding the whole complement first, so the width the set representation's bound sees is the width of the answer rather than of the widest intermediate. The work one build may spend rises with it, to the figure a record of three fields against its eight corners costs.That difference is built under the allowance, which is what puts a ceiling on what asking costs: a record over sixteen corners spends the whole of it and answers
"undecided", whichever way its fields and types divide them. An"undecided"is "not proven", never a claim that the relation fails. -
A mapping opened frees the keys no clause claims.
Validator(dict[str, int]).open().is_valid({1: "x"})wasFalseand isTrue. Openness is the default of the key-type region a schema's clauses leave over, so opening a mapping keeps what astrkey maps to and frees every other key-type, and closing it refuses them again. A record is the case where the clauses claim nothing at all, which is why opening one frees every key -- that is the special case, not the rule.The same reading ends a clause being read two ways according to an unrelated field:
Validator({"a": int, str: int}).close()dropped thestr: intclause because a field was declared beside it, and keeps it now, asValidator({str: int}).close()always did.openon a mapping writes a clause keyed by a complement, which is a shape the set representation declines, so relations about such a schema fall back to the rules (docs/explanation/decidability.mdrecords the decline). Membership is unaffected. Opening a record is unchanged in both answer and decidability. -
A pattern prints the way Python spells it. The
Regexmarker inside a rendered schema carried the pattern in Rust's spelling: double quotes where Python's own repr picks single, and\u{7}for a control character, which is a truncated escape wherever Python reads it. A repr is an expression that rebuilds the schema, and the marker beside it has a repr of its own, so the two now agree character for character. -
A render that gave up says so. A repr deeper than the renderer's own bound prints
<...>where it stops. It printed..., which is valid Python inside a subscript:evalon such a repr parsed it, built a validator, and handed back one that was not the schema printed -- a lossy rendering with nothing in it to say so. The mark is a syntax error wherever it lands, so a truncated render cannot be read back as a whole one. The bound is reachable: no single annotation can be written deep enough, but a chain of recursive definitions composes, and the documentation saying otherwise is corrected.tuple[T, ...]is unaffected -- that ellipsis is the annotation's own spelling. -
A constraint is put to the kind a literal's constant belongs to.
Annotated[int, MinLen(1)]is refused, because reading a length off an integer raises and the walk reads a raise as a non-member, so the schema would admit nothing and say nothing about why.Annotated[Literal[1], MinLen(1)]is the same schema one value narrower and compiled: it admitted no value and reported itself inhabited, a set that exists according to the library and holds nothing according to the walk. Every constraint family is affected -- a length or a pattern over a number, an order or a divisor over text -- and each is refused with the sentence its bare kind gets. A literal whose constant can be asked the constraint narrows exactly as its kind does, soAnnotated[Literal["ab"], MinLen(1)]is unchanged. -
A frozen set literal is refused, as its set sibling is.
{int}is refused with a sentence namingset[T];frozenset({int})fell past every arm to the literal fallback and compiled to a schema admitting one frozen set holding theinttype object, and no value a caller has. Afrozensetis not aset, so the arm that refuses the one never saw the other. Both are now refused, each naming the parametrized form to write instead. -
A
NamedTupleprints as its name, as every other class does.repr(Validator(Point))gaveintersection(tuple[int, str], Point)where a dataclass givesDCand a plain class givesPlain, anddocs/guides/schema-language.mdstates one rule for all of them. The schema is a meet either way -- anisinstancebeside a deep check of what the class declares -- and the reading that names the class looked only for a record of named fields, which aNamedTupledoes not have: its fields are positions. A union naming such a branch said the same thing twice over for the same reason, and now names the class. -
An arity refusal names the annotation it is about.
list[int, str],set[int, str]andfrozenset[int, str]were refused with "expected exactly one type argument" -- a count, naming neither the annotation it was about nor what to write. A caller with one long annotation had nothing to search for. Each now names the spelling, says how many arguments were written, and says what to write instead, which differs by kind: a list of fixed length is the list literal[A, B], and a set schema is homogeneous, so several element types are their unionset[A | B]. -
A walk reports what it found, at the edges a corpus reaches last. A dict holding a key whose
__eq__raises was reported as not being a dict, which sends a reader to the wrong value: it is a dict, it is not a member by the comparison-raises rule, and the field it cannot be shown to hold is reported missing. AndMultipleOfover a step that is not a number is refused at build rather than compiled: the constraint isvalue % n == 0, atimedeltaremainder equals no integer zero, and the validator that came out refused every value without saying why.int,float,DecimalandFractionsteps are unchanged. -
A union summary names its branches, and keeps what stopped the walk. The summary names each branch "as each would name itself alone", and two branch kinds had no name of their own: a
complementread as the wordcomplementwhere alone it saysnot str, and arecursivebranch as the wordvaluewhere alone it names what it admits. Both name themselves. And a branch whose failure isrecursion_limit,recursion_loop,mutated_during_validationorpredicate_errorkeeps that report: each says the walk stopped rather than that the value is outside a set, each fails at the union's own location, and the summary counted that as no progress -- so a value nested past the walk's ceiling, or holding itself, came back as "matched no branch" with the reason dropped. -
A report keeps the promises the error model makes.
fail_fast=Truestops at the first failure, and two sites reported two: a union aggregated the whole of its closest branch, and a mapping clause reported the key and the value together. Both report one, on the object path and the JSON path alike; the branch is still walked whole, because which branch is closest is measured by how far each descended. An undeclared integer key is named in the path as an integer, soerr.path[-1]indexes back down to the entry -- one reading of a record gave the string of its digits and the other the integer, for the same value. A predicate's raised error is summarized like every other value a message carries rather than copied whole. An undeclared key's value reads as a Python repr, as every other value does. And a__repr__raising a fatal signal while a message is built propagates it rather than folding it into<unrepresentable>, which is the rule at every other site a value answers a question. -
An annotation builds the schema it names, or is refused. Four forms were read as a different schema, with no message saying so.
typing.Tuple[()]is the empty tuple and built every tuple, admitting(1,), because a bare legacy alias and an empty parametrization are told apart by whether a type-argument list is present rather than by whether it is empty. A marker standing for the constraints it yields -- the grouping protocolannotated_typesdocuments, whichIntervalandLenare written against -- was read by attribute alone, so a marker of your own left the schema admitting exactly what it excludes.{"a": int, "a?": str}names one field twice and built a record admitting nothing; it is refused.Literal[int]names no constant and built theintschema; it is refused. And aRegexmarker carrying something that is not text names what it carries rather than reporting every one as bytes. -
A string kind holds the characters no pattern matches. A
stris a sequence of code points and a lone surrogate is one of them:"\ud800"is one character long and is a member ofstr. No codec encodes it, and aRegexmatches the text of a string, so no pattern matches it -- which the walk has always said. The kind's universe stopped where the codecs do, so the difference betweenstrand a catch-all pattern came out empty:Validator(str).relation_to(Annotated[str, Regex("(?s).*")])answered"subset"against a string a caller can write in one line. It answers"not_subset", and the difference between the two reports the character that refutes it. A length bound counts that character as the one character it is, and inclusion between two patterns is unmoved. -
A literal counts as one value only where its constant is one.
Literal[c]denotes the values ofc's type equal toc, which is one value where that type's equality is Python's own or compares by identity, more than one where__eq__answersTruefor its siblings, and none where the constant does not equal itself. Counting every literal as one decidedAnnotated[set[Literal[E.A]], at.MinLen(2)]empty for an enumeration whose__eq__lies, while{E.A, E.B}validates against it, and reported"not_subset"forAnnotated[set[Literal[float("nan")]], at.MinLen(1)]againstint, which asserts a value the schema has none of. The count asks the oracle, so an unreadable constant leaves the bound unread and the relation undecided.set[None],set[bool]and an ordinary enumeration are counted as before. -
An integer bound at the end of the carrier keeps the integers past it. The integer component spells a set as intervals, and the bounds a schema names are 64-bit while Python's integers are not. Complementing a half-line that begins at the smallest such bound needs the integer just below it, which had nowhere to go, so the complement came out empty:
Validator(int).relation_to( Annotated[int, at.Ge(-2**63)])answered"subset"while-2**63 - 1is anintthat bound refuses, andintersection(int, complement(...)).is_empty()answeredTrueover a difference holding that value. The answers are"not_subset"andFalse, andLe(2**63 - 1)answers the same way at the other end. A bound the carrier spells is decided as before, soAnnotated[int, at.Ge(-2**63), at.Le(-2**63)]is proved belowat.MultipleOf(2). -
A container subclass does not talk its way into a schema. A schema over a container denotes the values it holds, and a subclass may override
__len__or__iter__and answer anything. The override was believed, soValidator(set[int]).is_valid(s)wasTruefor asetsubclass whose__iter__yields integers over storage holding"a", andAnnotated[str, MinLen(3)]admitted astrsubclass reporting nine over one character. Both answerFalsenow, onis_validandvalidatealike. Every container the walk reads answers this way:str,bytes,list,tuple,set,frozensetanddictare counted through their base type's__len__, andsetandfrozensetare walked through its__iter__. A subclass that overrides neither is read where it lies, so aNamedTupleand an ordinary container subclass pay nothing. -
A set is at most as long as the values its element denotes. A sequence takes any length by repeating one element and a set does not: it holds each member once, so
Annotated[set[None], MinLen(2)]denotes no set at all. The refinement was read as inhabited, and an inhabited subject is what lets a kind mismatch refute an inclusion -- sorelation_toanswered"not_subset"forAnnotated[set[None], MinLen(2)]againstNone, asserting a value that does not exist, andis_emptyansweredFalse. Both answer for the set now:is_emptyisTrueand the inclusion holds vacuously.set[bool]decides the same way at three members,set[int]at any bound, and a list is unchanged at every one. - A dict has one entry for
1and forTrue.Truehashes as1and equals it, so{1: "a", True: "b"}is a dict of one key -- while the descriptor held the two as separate slots and read a schema requiring both as inhabited.is_emptyansweredFalseforintersection(complement(Validator(dict[Literal[1], str])), complement(Validator(dict[Literal[True], str])), Validator(dict[Literal[1, True], str])), which admits no dict at all. The same shape over two integers is inhabited and still says so.
Literal[1] and Literal[True] stay disjoint: a key is an int or a
bool and the walk tells them apart. What changes is that no dict carries
both of them at once.
- A character class carrying --, &&, ~~ or a nested [ is refused.
Those combine classes in this engine and are literal characters to re, so
one pattern denoted two sets and compiling it said nothing about which:
Annotated[str, Regex(r"[\w--\d]")] admitted the non-digit word characters
here and the word characters plus - there. re gives three different
answers to the four forms -- it raises on the doubled hyphen, warns that it
reserves the two symbol operators, and says nothing at all about a nested set
-- so a reader porting a pattern found out at once, eventually, or never. Each
now raises a ValueError naming the operator this engine would have read.
Escape the characters to mean them literally, or write the classes out. A
POSIX class ([[:alpha:]]) is read rather than refused: it is the divergence
docs/guides/refinements.md already names, with both readings shown.
- A pattern in extended mode may end in a comment. (?x) makes # run to
the end of the line, and the anchor a whole-string match needs was appended
after it -- so the closing half was swallowed and a pattern re accepts
raised here. It is the form a long pattern is written in.
- A relation answers for the set a schema denotes, at the edge of every
kind. Eight readings named a set the schema does not have, and each is one
wrong answer a caller could see. is_empty reported an inhabited schema empty
and is_subtype_of reported an inclusion a value refutes, for:
a length bound over a str or bytes, which counted every symbol but the
newline; a str complement, whose universe was every byte string rather than
the valid UTF-8 ones, so a difference holding only the rest read as inhabited; a set whose element kind is unhashable, whose members were cut
although a subclass defining __hash__ is a legal member; an integer bound or
step at the end of the 64-bit range, whose residue class was read as another;
and a float bound written with an integer past 2^53, which no float equals
and which was rounded to one that does.
- A refutation stands on a value. relation_to answered "not_subset" --
which asserts a value of the subject lies outside the other schema -- where no
such value exists: through a recursive reference the lowering had cut, for a
dict[bool, V] against a clause listing both booleans, for a dict[int, V]
against the bool keys it admits, for a clause whose key cannot spell a field
name, for a union of literals whose only missing member is float("nan"), for
a container of a meet of two unrelated classes, and for a class whose
metaclass answers issubclass by running code or by raising. Each answers
"undecided" or "subset" now, and is_subtype_of is unchanged on all of
them.
- is_valid and validate are one answer at the walk's depth bound. A
homogeneous list, tuple or set of a scalar kind was admitted by the first and
refused by the second at the deepest level a walk reaches.
- A record resolves a key the way the dict does. A str subclass carrying a
field's text was read as that field where a catch-all clause sat beside it,
and as an undeclared key where none did, so one value had two answers.
- A Regex marker is immutable. It is hashable and a schema holds it, so a
pattern rebound after the fact changed the hash of a value already in use.
- MultipleOf is a remainder equal to zero, which is what the constraint
documents. The check read the remainder's truthiness, which differs for a type
whose __bool__ and __eq__ disagree.
0.0.11 - 2026-09-15¶
A performance release. Nothing a caller writes changes: every entry below is the same answer arriving for less, or a platform the project states it supports and now proves. The frontend is the release's subject -- compiling an annotation got cheaper three separate ways, and the walk over a record got cheaper where a caller's dict already holds interned keys.
The one fix is PyPy's: a tuple subclass that overrides __len__ could send
the walk past the end of its storage, which is a crash rather than a wrong
answer, and it reached MinLen/MaxLen over such a subclass too.
Changed¶
- Compiling a refinement is about three times cheaper. The frontend read a
marker's optional attributes by trying them: a marker carries one of
ge,gt,le,lt,min_length,max_length,multiple_of,pattern,flagsandfuncand not the other nine, and each absence answered by raising an exception that was built, caught and dropped -- four hundred of them to compile fifty fields.
Two changes remove them. The absences that could be asked for are asked,
through PyObject_GetOptionalAttr where the runtime has it, which is 3.13
onward. And which names a marker can carry is a property of its type --
every annotated_types marker is a slots dataclass, so Ge.ge is the
descriptor that reads the slot and Ge.gt does not exist -- so the type is
asked once and the answer kept, which removes the rest on every interpreter:
below 3.13 there is no non-raising getattr, and func was asked with a bare
one even above it. A marker that keeps its values in a dictionary of its own
is read from that dictionary, which answers for a name it does not hold
without raising; a type with a __getattr__ hook answers for names no
dictionary holds, and is asked for everything exactly as before.
Fifty Annotated[int, Ge(0)] fields compile in 48 us where they took 153
on 3.14 and 45 where they took 144 on 3.12, and as a TypedDict in 100
where they took 240 and 86 where they took 238 (release build, idle
machine, best of five runs of three hundred, twice).
-
A validator no longer imports
dataclassesto ask whether a class is one. Every class node imported the module and called through it; the function is held after the first class that asks, and only after one asks -- importingdataclassespullsinspect,copyandfunctoolsin with it, and the tracked objects they leave behind are walked by every later garbage collection, which costs a program that never compiles a dataclass 6.45% of its compile -- which is an instruction count, taken twice. A fifty-field dataclass compiles in 32.7--34.2 us against 34.4--35.8 (release build, idle machine, three runs each); a program that compiles none imports nothing. -
Building a validator is about four times cheaper. The frontend asked the interpreter to import
typingand resolveget_origin,get_argsand the qualifier forms once per node of the annotation it was reading, for a modulesys.moduleshas held since the first one. It holds them, as the cache beside them always said it did: a fifty-field record compiles in 222,939,220 instructions where it took 939,032,142. -
Validating a record is cheaper when the dict's keys are interned, which is every dict written as a literal, every
**kwargsand every__dict__. A validator's declared keys are interned too, so the probe compares pointers rather than bytes: a fifty-field record walk reads 29% cheaper with both sides interned, and about a percent cheaper with only ours. -
PyPy 3.11 is a stated target. The
Implementation :: PyPyclassifier anddocs/get-started/installation.mdname the four wheels published for it from 0.0.10 onward -- manylinux and musllinux, x86_64 and aarch64 -- so a consumer there can tell a supported platform from an accident of the build matrix. Every push builds the extension against PyPy and imports it: the C API PyPy offers is not CPython's, and the difference shows at import rather than in any answer a validator gives.
Fixed¶
- A
tuplesubclass that overrides__len__no longer takes PyPy down. The tuple walk read its element count fromPyTuple_Size, which is the storage on CPython and the object's own__len__on PyPy'scpyext: a subclass reporting ten over one element made the walk read nine slots past the end of the allocation, andValidator(tuple[int, ...]).is_valid(...)segfaulted PyPy 3.11 rather than answering. A subclass is read through the base type's own slot, which means the same thing on every interpreter, and is walked over the elements it holds -- the answer CPython gave all along. An exact tuple is read where it lies, and so is a subclass that inheritstuple.__len__rather than overriding it — everyNamedTuple— which the first form of this repair copied along with the liars. Telling them apart costs one type lookup per validation: a three-fieldNamedTuplevalidates in 69 ns against 57 at 0.0.10, where copying it cost 100.
The same reading fixes MinLen/MaxLen over a list or tuple subclass on
PyPy, which had believed the overridden __len__ while the shape beside it
counted the storage.
0.0.10 - 2026-09-13¶
A second representation decides the three relations. Where the structural rules
declined a pair, a set built per kind is asked instead, so is_subtype_of,
is_equivalent and is_empty answer over a wider fragment without any of them
answering differently: every relation this release adds moves a pair from not
proven to decided, and a True still means what it meant. relation_to is the
surface that tells those two apart, in three answers where the boolean has two.
typing.Any is the lattice top, a schema is built in the lattice normal form,
and Validator.simplify is deprecated because the reduction it promised is the
schema a caller already holds. Every compiled entry point takes its arguments
positionally. This is a 0.0.x pre-release and those are breaking changes;
each is written out below.
Added¶
Validator.relation_to(other)reports the inclusion in three answers whereis_subtype_ofreports two. AFalsefrom the latter folds together a value of this schema the other rejects and a question the procedure declines;"subset","not_subset"and"undecided"keep them apart:
from valgebra import Validator
assert Validator(bool).relation_to(int) == "subset"
assert Validator(str).relation_to(int) == "not_subset"
assert Validator(bool).is_subtype_of(int) is True
"subset" is exactly what is_subtype_of answers True for, so no existing
answer moves. A "not_subset" is a statement about a value: some member of
this schema is outside the other, which the completeness probe holds by asking
its universe for that value.
Which pairs earn one has grown since this entry was written, and keeps
growing: a refinement against another of a different kind, two sequences whose
elements share no value where a length bound rules the empty one out, a
sequence against a bound it cannot meet, a class met with its attributes
against a union or a recursive record, and a complement against a class. Each
moves a pair from "undecided" to "not_subset", which is the direction the
procedure may move in. docs/explanation/decidability.md is
where that list lives rather than here; this entry is the answer, not its
reach.
- A
NamedTupledenotes the tuple its fields lay out, so a relation between one and that tuple is decided rather than declined:
from typing import NamedTuple
from valgebra import Validator
class Pair(NamedTuple):
x: int
y: int
assert Validator(Pair).is_subtype_of(tuple[int, int])
A named tuple's positions are its attributes -- the class lays both down at once -- and the schema says so instead of describing the attributes alone, which denoted a wider set than the class has. A failing field reports its position rather than its name, because the shape carries positions; a passing instance is read once rather than twice, and checks about a third faster.
- A union of literals is decided as the finite set it denotes, at any width and in both directions. A literal denotes one value, so a union of them denotes a set of values, and inclusion between two such sets is membership of every value of one in the other -- found is a proof, and one value found nowhere is a refutation naming what stands against the inclusion:
from typing import Literal
from valgebra import Validator
codes = Validator(Literal[tuple(range(10_000))])
shifted = Validator(Literal[tuple(range(1, 10_001))])
assert codes.relation_to(shifted) == "not_subset"
That pair read "undecided" at a thousand members, because the rules
distributed one table against the other and spent the decision budget on the
product. Membership is a walk of the two tables instead: ten thousand codes
against ten thousand decide in about 9 ms, and the containment they do
prove falls from 237 ms to 6 ms. Literal[float("nan")] is the empty set --
no value equals nan -- and the empty set is below every schema, which the
core could not say before because a literal had no emptiness of its own.
Two tables written in different orders are the same case: relating two
validators renumbers one pool into the other, and a member set that is
renumbered is put back in canonical order rather than left as the other
validator happened to number it.
-
Relations over a bound on a float are decided. A bound was lowered into the descriptor only over whole numbers, so anything needing the descriptor and mentioning
Annotated[float, Gt(0)]stayed undecided:float > 0was not known to be belowfloat, nor disjoint fromint, nor fromfloat < 0. A float bound is now a set of floats, with the side chosen by the base rather than by the operand's type —Gt(0)carries the integer zero and orders the floats all the same — andnansits outside every interval, as Python's own comparisons put it. The completeness probe's random sweep reports fewer undecided relations in both directions, with none refuted by a value. -
Schemas compare as sets. Each kind of value carries a representation closed under union, intersection and complement — integers as interval sets per residue class, floats as intervals over the ordered line with a bit for
nan, strings and bytes as regular languages, sequences as automata over value sets, sets as powerset lines, dicts as map atoms with a default per key kind, classes as an order, objects as records over their attributes — soa <= bis asked asa & ~badmitting no value, which is what the relation means. Where the structural rules decline, that question is asked and answered:
from typing import Annotated, Literal
import annotated_types as at
from valgebra import Regex, Validator, complement, intersection
assert Validator(Annotated[str, Regex("a")]).is_subtype_of(Annotated[str, Regex("ab?")])
assert Validator(Annotated[int, at.MultipleOf(4)]).is_subtype_of(
Annotated[int, at.MultipleOf(2)]
)
assert Validator(bool).is_subtype_of(Literal[True, False])
assert Validator(bool).is_subtype_of(Annotated[int, at.Ge(0)])
assert Validator(dict[Literal["a"], int]).is_subtype_of({"a?": int})
assert intersection(list[int], list[str]).is_subtype_of([])
assert Validator(tuple[int]).is_subtype_of(complement(tuple[str]))
Container meets, double complements, one regular language inside another, a
kind against its own literals, one step dividing another, and the emptiness of
a dict schema are decided this way. Twenty-five relations that answered False
answer True, and the same shape written any other way is decided alike: a
respelling such as union(A, complement(union(A, nothing))) is the universe.
Building a set representation costs about two orders of magnitude more than a rule that already answers, so it is asked only where the rules decline, and only for a schema it can build within a bound on the nodes it reads, the nesting it descends and the work it spends. Past any of those the answer is the conservative one, as before. What stays conservative is recursion, a length bound over a shape that is not text, an attribute record beside a builtin kind, and a predicate.
- An integer key stays an integer in an error path. The
patha failure reports is what a caller walks back down to the offending value, and every mapping key arrived as text -- so a dict keyed by numbers reported a location that indexed nothing, andd[2]andd["2"]were indistinguishable. A key that is a string or an integer is now itself; anything else has no spelling in a path made of those two and appears as its repr, as before.
from valgebra import ValidationError, Validator
raised = False
try:
Validator(dict[int, int]).validate({1: 1, 2: "x"})
except ValidationError as error:
raised = True
assert error.errors[0]["path"] == (2,)
assert raised
-
A validator cannot be pickled, and says what to send instead. It holds the classes and callables its schema names, so the schema is what travels; rebuilding is about as cheap as unpickling would be.
ValidationErrorpickles as before. -
A length bound on a list or a tuple is decided. A length is a regular property of a sequence -- "any element, that many times" -- so the representation that holds sequences holds a bound on them, and a bound that used to be opaque to everything but a string is now part of the algebra.
from typing import Annotated
import annotated_types as at
from valgebra import Validator
assert Validator(Annotated[tuple[int, int], at.MinLen(3)]).is_empty()
assert Validator(Annotated[list[int], at.MinLen(3), at.MaxLen(2)]).is_empty()
assert Validator(Annotated[list[int], at.MaxLen(0)]).is_equivalent([])
assert Validator(Annotated[list[int], at.MinLen(2)]).is_equivalent([int, int, int, ...])
A set and a dict have a length their representations do not count, so a bound over one of those still stands.
- A recursive schema is decided against the kinds its body admits. A
reference is a cycle and a set representation has no room for one, so every
relation over a fixpoint used to fall to the structural rules -- which read
shapes, and cannot tell that a JSON value and a
bytesshare no value. The body is now unfolded once before the sets are built, with a bound standing where the reference was: the top where the schema is used positively, the bottom under a complement, which is what keeps a difference sound.
from valgebra import Validator, anything, complement, intersection, recursive, union
json = recursive(lambda j: union(None, bool, int, float, str, [j], {str: j}))
assert intersection(bytes, json).is_empty()
assert intersection(tuple, json).is_empty()
assert Validator(bytes).is_subtype_of(complement(json))
assert json.is_subtype_of(anything)
- A recursive schema is one schema wherever it is combined. Merging a
compiled validator used to copy its definitions, so two occurrences of one
fixpoint became two definitions and every law that compares terms failed on
it:
intersection(json, complement(json))was not empty andunion(json, complement(json))was not the top, for the same schema object on both sides. A merge now reuses definitions it already holds, and a fold that leaves one unreachable drops it -- so the top built that way is the top built any other way.
from valgebra import (
Validator,
anything,
complement,
intersection,
nothing,
recursive,
union,
)
json = recursive(lambda j: union(None, bool, int, float, str, [j], {str: j}))
assert intersection(json, complement(json)) == Validator(nothing)
assert union(json, complement(json)) == Validator(anything)
- Two spellings of one schema are one schema. A record's fields, a map's
clauses, a refinement's markers and a union's members are sets, so the order
they were written in is no longer part of the term:
==says so,hashagrees, a union of two spellings folds to one member, and a validator is a usable dictionary key whatever order its schema was written in. A repeated marker is dropped, since a constraint written twice narrows once.
from typing import Annotated, Literal
import annotated_types as at
from valgebra import Validator, union
assert Validator({"a": int, "b": str}) == Validator({"b": str, "a": int})
assert Validator(Literal[1, 2]) == Validator(Literal[2, 1])
assert Validator(Annotated[int, at.Ge(0), at.Le(9)]) == Validator(
Annotated[int, at.Le(9), at.Ge(0)]
)
assert union({"a": int}, {"a": int}) == Validator({"a": int})
repr prints the canonical order rather than the written one, which is
the visible half: {"name": str, "age?": int} renders as {'age?': int,
'name': str}. It still rebuilds the schema. A test pinning the written order
of a record's fields, a map's clauses or a refinement's markers needs
updating; one pinning a union's or a literal's does not, since those keep the
order they were built in.
- A PEP 695
typealias that names itself builds the fixpoint it writes. The alias is the binder: it is reached again while its own body is read, and there is no lambda to carry the fixpoint, so the alias carries it. What it builds is what the explicit call builds, and mutual recursion is two aliases naming each other. An alias naming itself outside a structural constructor denotes no set and is refused when the validator is built, as an unguardedrecursivealready was. Before, such an alias was refused as a schema too deep to compile.
from valgebra import Validator, recursive, union
type Json = bool | int | float | str | list[Json] | dict[str, Json] | None
assert Validator(Json).is_equivalent(
recursive(lambda j: union(None, bool, int, float, str, [j], {str: j}))
)
-
The three construction bounds are importable:
MAX_SCHEMA_DEPTH,MAX_DEFINITIONSandMAX_SCHEMA_NODESare exported fromvalgebraand listed in__all__, so code sizing a schema against a bound reads the number rather than repeating it. -
A class with declared attributes is the meet of its
isinstanceatom and a record of its attributes, and each half is a set the algebra relates on its own: an object schema is below its own class, an attribute record relates to another by width and depth whatever class it came from, and a record whose required attribute admits nothing is decided empty and one whose attributes are inhabited is decided inhabited — which the class half, being opaque, used to take away. The surface is unchanged:repr(Validator(Point))isPoint, a union names the class in its branch list, and a value of the wrong class reports oneinstance_typeviolation. -
An
intersectionstops collecting violations once a member rejects the value itself rather than something inside it, the ruleAnnotated[...]already applied between a base and its constraints. A member that fails inside the value leaves the others meaningful and they are still collected. -
Widening a literal union is decided by containment rather than by the product of the two member counts, so a table whose members are the same constants as the wider one's relates at any size. Constants pool by value, so two tables written independently share theirs and relate the same way.
-
~~AisA, a union carrying a schema together with its complement is the top, and a meet of that pair is the bottom, all settled where the schema is built. The decision procedure has no rule for these shapes and does not meet one built through the constructors; a shape built another way — a recursive definition, a respelling, constants equal but not identical — reaches the procedure and is not decided.repr,==, and the code a violation reports follow the canceled form:complement(complement(int))reportsint_typewhere it reportedunexpected_match, andintersection(int, complement(int))reportsno_matchnamingnothing. A predicate and a class with anisinstancehook are exempt from the two canceling folds: the law is about sets, and an atom that answers by running code is not one. -
A meet of two record schemas is decided empty when a key one side requires cannot hold — because the types the two give it share no value, or because the other side is closed and does not declare it.
{"a": int} & {"a": str}is empty, and so{"a": int}is below~{"a": str}. Only a required key empties a meet: two mappings, or two optional fields, always admit the empty dict. -
A fixed-length sequence is decided against a union of fixed-length sequences it splits across, where no single branch contains it:
tuple[int | str, int]is belowtuple[int, int] | tuple[str, int]. The rule needs a fixed component count, so a homogeneous or variadic sequence is not decomposed, and branches of another container or arity drop out rather than blocking it. -
A literal carries the kind of its constant, so it is decided against another kind:
Literal["a"]is below~int, andLiteral["a"] & Literal["b"]is empty.Literal[1]andLiteral[True]are disjoint although1 == True, because a literal pinstype(x)exactly. The rule applies to the builtin scalars, whose equality is Python's own; a meet of twoEnummembers stays conservative, since user-defined equality can admit one value for two constants. -
A recursive schema is decided below its own body written out, and a refinement of a union below that union:
recursive(lambda t: union(None, {"next": t}))is a subtype ofunion(None, {"next": <that schema>}), andAnnotated[int | str, Ge(0)]ofint | str. Trying a union's branches one by one commits to a branch, and a subject that lands in the union only once a reference is unfolded or a refinement drops to its base got no answer from it. Both rules are sound alone, so where both apply both are asked. -
Every
ValidationErrorcarries the six attributes the error model documents, however it was made. The model describes failures and an error built by hand reports none, so it reads as empty — empty strings and empty tuples — rather than raisingAttributeErrorfor an attribute the type declares.
Changed¶
-
A length bound over a container that repeats one element decides whether the schema has a value, where it was left unknown. A value of any length is as many copies of one element, so the element decides it: a bound of zero is met by the empty container, a longer one by repeating an element. Three things follow. A recursive schema every unfolding of which needs one more element is reported empty, which the completeness ledger carried as a relation it could not decide. A refutation about such a schema is believed, so
list[int]with a length bound is decided not below a tuple, by a rule rather than by the set representation. And the refuting half of the decision workload, whose hardest case was a fixed sequence with an unfillable position, falls by two orders of magnitude; the instruction gate holds the figure. -
A relation between two classes is decided by a rule. A class whose metaclass leaves
isinstancealone is read as holding an object -- the open world the set representation already works in, and the assumption every refutation this library makes about a class already rested on -- so the rules stop deferring to the sets for an answer the library had committed to: two unrelated classes read 1.2 us against 100, adictsubclass against a list 1.4 against 37, and a plain class against a dataclass 2.2 against 472. The answers are unchanged. A class whose metaclass answers with code of its own is read as before, which is not at all, and the decidability page states the assumption and where it is wrong. -
A length bound over a string or a bytes decides whether the schema has a value, where it was left unknown. A string takes any length, so a bound its own lengths admit is met --
Annotated[str, MinLen(1)]is the non-empty string and it has one. Every refutation about such a schema is believed rather than left to the set representation: a non-empty string against another kind reads 0.9 us against 195, and against a mapping 0.9 against -
A bound over a base whose values have no length still says nothing, and the reading declines.
-
A rule that answers for a shape and then declines hands the pair on, where it used to end the question. A refinement takes its base's supertypes and nothing else; a union supertype takes a subject that lands in one branch. A pair either leaves unproven now reaches the readings that decide what a pair with no rule is worth -- two sets that share no value, then the oracle, then the supertype's own shape. A bounded list against a mapping or a union of scalars reads 1.2 us against 395.
-
A subject outside a base is outside every refinement of that base. The value that refutes the one refutes the other, and it is the same value, so the refutation carries where the proof cannot: being inside the base says nothing about the constraints. A tuple against a length-bounded list reads 0.8 us against 460.
-
A class laid out as a builtin decides a relation by a rule. A class deriving from
dictholds mappings and nothing else -- a subclass inherits the layout and cannot lay down a second -- so a list is not below it and the pair is refuted where it was left to the set representation:list[int]against such a class reads 1.2 us against 35. A class deriving from no builtin is not read this way and stays undecided, because a subclass of it may derive from one: an instance of a class built on that one and onstris a string and an instance of the first. -
A pair whose kinds cannot overlap decides by a rule. Two distinct container kinds share no value, so every value of the subject is outside the supertype and the inclusion is refuted -- where the relation was left unproven and settled by lowering both sides into the set representation.
list[int]againsttuple[int, int]reads 0.6 us against 75 us, a mapping against a list 0.7 against 37, with the same answers. -
A key one record requires and the other does not declare decides the pair by a rule. A clause governs the keys a value carries and requires none, so a record open to undeclared keys still holds a value without that key, and that value is one the supertype rejects. The relation was left to the set representation, which lowers both records to answer it -- and since a
TypedDictis open by the typing spec, that was every relation between two of them: 1.0 us against 268 us for two eight-fieldTypedDicts, on the machine the performance page names. -
A
TypedDictvalue is read by its declared keys, as a closed record's is. ATypedDictis open -- the typing spec admits keys it does not declare -- and an open record was scanned key by key where a closed one was read by its keys, for a clause that admits any string. The keys settle it either way: every declared field is probed, and a key to spare is admitted when it is a string and refuses the record when it is not, which no key need be resolved to say. The same fifty-field value reads about a quarter faster as aTypedDictand its error report about a sixth, and neither answer moves. -
Two schemas built alike share their nodes, so a question that reaches both is answered by identity rather than by walking two trees. A relation between a record schema and an equal one built separately reads 1.07M instructions against 4.97M under the core decision workload; the whole of that workload reads 21% down and the schema-transformation workload 4.5% down (
scripts/perf_gate.py --decision --core). Building a validator pays 0.6% for the sharing, and the membership walk is unmoved. Nothing about what a schema denotes changes: the test that decides sharing is stricter than equality -- two spellings of the top stay two nodes, andreprgives back the one that was written. -
Explaining a failure over a record costs a third less. The accepting walk scans a dict once and resolves each key it finds through a map built with the validator; the explaining walk asked the dict for each declared key by name, and a Rust string handed to a dict lookup is decoded into a fresh Python string and hashed before the probe can start -- once per field, per call. The declared keys are interned with the validator, as the attribute names already were, so the lookup is the probe alone. A fifty-field record reporting one bad field moves from 2.38 to 1.53 of pydantic-core's time, and the shape's ceiling comes down from 3.5 to 2.5. No answer changes.
-
The membership walk costs a third less. Every scalar arm of the walk ended in a helper that passed a boolean through and recorded a violation when it was false, and every element of a sequence went through a second helper between the loop and the walk. Both were out-of-line calls doing almost nothing: on a list of integers they were fifty of the hundred and fifty instructions spent per element. The two are inlined and the violation-recording half is marked cold, so the accepting path is a test where the answer already is. Measured on the fixed binding workload, 661.6M instructions against 968.9M, and against pydantic-core a 1,000-element array moves 0.88 to 0.57 of its time, a fifty-field record 0.58 to 0.49, and a JSON document 0.86 to 0.81. No answer changes.
-
Building and composing a schema costs less. A field name was owned outright by the field that declared it, so every pass that rebuilds a schema — opening or closing its records, reindexing it onto another validator's pools, simplifying it — copied the name of every field it carried across. On the core's fixed workload those copies were 38% of every heap allocation the crate made. A name is now shared: carrying it is a refcount bump and no allocation. The workload runs in 161.0M instructions against 233.5M, and compiling a fifty-field record costs 13.7 µs against 14.2. No answer changes.
-
A schema is built in the lattice normal form. The constructors folded two laws and left the rest standing, so
union(int, int)renderedint | intand compared unequal tointwhileunion(int, complement(int))renderedanything—==was equality of nothing in particular, andreprshowed a shape no rule was written for. Members of a join or a meet are flattened, ordered and deduplicated; the identities and the absorbing elements apply;~anythingisnothingand~nothingisanything; and a join of one member is that member. Sounion(str, int) == union(int, str),intersection(int, anything) == Validator(int), and==is equality of a canonical form.
Three things a caller may see. repr shows the normal form, so a join renders
its members in that order — a kind before a literal, for instance, while
literals and classes keep the order they were written in, their pool slots
being what orders them. A union's expected message lists its branches the
same way. And Literal["x"], a join of one member, is that literal: it reports
literal_error where it reported union_error.
Absorption is the one law left standing: A | (A & B) is A only when A
contains A & B, and containment is the decision procedure — running it
wherever a schema is built is the cost this design refuses everywhere else.
is_equivalent decides it.
- A bare container class is its kind.
listandlist[object]admit the same values — every list, a subclass instance included — and were different sorts of thing: a sequence node in one case, anisinstanceatom in no kind at all in the other, so neither spelling was decided below the other andrepr(Validator(list))saidlistwhere the schema said otherwise.list,tuple,set,frozensetanddictname their kind's whole set, which is what the typing spec assigns an unparameterized generic and what the membership check always performed; the two spellings are one schema and compare equal.str,bytes,intandfloatalways read this way.reprfollows the schema, soValidator(list)renderslist[anything].
A class built on a builtin narrows that kind rather than standing beside it, so
it relates to it: Validator(MyInt) is below Validator(int) and
Validator(MyStr) below Validator(str), and a meet of the two is empty. A
class built on no builtin narrows nothing and relates to a kind in neither
direction — class Both(Plain, MyStr) builds and its instances are strings, so
a plain class's instances are not confined to any kind.
-
Every argument the compiled surface takes is positional.
Validator, the combinators, and every method on a validator declare their parameters positional-only, matching the stub that already wrote them that way: a call naming one —v.is_valid(obj=x),Validator(schema=int),complement(schema=int)— raisesTypeError.fail_fastis the one keyword the surface takes and it is keyword-only, as before. A stub that permits a keyword the extension refuses type-checks code that cannot run, and the two disagreed in nine places. -
A
TypedDictis open, which is the set the typing spec assigns it: a dict carrying keys the class does not name is admitted, and the keys it does name are checked and required exactly as before.closed=Trueandextra_items=T(PEP 728) are obeyed where the runtime provides them. The dict-literal form{"name": str}stays closed — it is this library's own spelling, and a schema written as a shape means that shape. Code relying onValidator(TD)to reject an extra key should write theTypedDictclosed=True, or use the dict literal. -
A map key schema narrowed by a constraint is refused where it is written. A clause's key says which keys it governs, and that must be a type —
str,int, a union of them — or aLiteral, which names the keys one by one.{Annotated[str, MinLen(2)]: int}anddict[Annotated[int, Ge(0)], str]now raise at construction. A narrowed key names part of a type, and two such clauses can overlap without either containing the other, which is a question this map model does not answer the same way twice. To constrain the keys themselves, check them beside the mapping rather than inside it. Keys that name a whole type are unaffected,dict[tuple[int, int], V]included. -
typing.Anyis the lattice top. It denotes what it always admitted — every value — and it is now the same schema asanything, so every law and every relation reaches it:Validator(Any) == Validator(anything),complement(Any).simplify()isnothing,intersection(Any, complement(Any))is decided empty, andintis decided belowAny. A gradual type is held apart from the top for a second question, consistency at the boundary between typed and untyped code, which a validator has no site for and never asked. What is kept is the spelling:repr(Validator(Any))is stillAny, andrepr(Validator(anything))is stillanything. The spelling is not part of the set, so two schemas differing only in it are equal and nothing decides anything by it.
Code that read intersection(Any, complement(Any)).is_empty() as False, or
Validator(Any).is_equivalent(anything) as False, now sees the opposite.
Membership is unchanged: Any admitted every value before and admits every
value now.
-
A constant is a value rather than an object. Two equal builtin scalars built separately — two
"code_00042"strings read from different files — pool into one constant, where pooling by object identity made them two and left a schema mentioning both with two nodes no rule could see as one. The rule is a literal's own: same exact type, and equal.Literal[1]andLiteral[True]stay two constants because the types differ;Literal[0.0]andLiteral[-0.0]are one, because the values are equal and the sign of zero is not part of either; ananand an integer too wide for the key pool by identity, sincenanequals nothing at all and a wide integer has no key. Two independently written thousand-member tables relate at any size as a result. -
reprrenders an expression that rebuilds the schema. Three forms rendered something that either was not Python or was Python that builds a different schema: a recursive schema showed its back edge as..., an open record showed its catch-all as..., and both read back asLiteral[Ellipsis], an ordinary dict key; the nullary product printedtuple[], which is not an expression. They render asrecursive(lambda X: {'v': int, 'n?': X}),{'name': str, anything: anything}andtuple[()]. Two forms remain a rendering rather than a round trip, because neither is syntax: a class prints its name and a predicate printsPredicate(...). -
A validator names the package it is imported from.
Validator.__module__isvalgebrarather than the private extension underneath, which the API reference reserves the right to rename and tells callers not to import; the class isfinal, which it was already at runtime, and the annotation says so to a type checker. -
A list or tuple counts one level of the construction depth bound, not two, so a schema can nest twice as deep before the bound refuses it: a chain of 128 nested lists now builds where 64 was the limit, and a chain that pins a length on each list reaches 64 where 43 was the limit. The sequence node carries its elements directly rather than as a regular expression over them, and the two levels a list spent were the expression's own constructors — levels a walk descended and a reader had no way to see. The bound itself is unchanged at 128 levels, and no schema that built before is refused now.
-
A schema refused for depth says so by name. The frontend's own descent limit stood at the same 128 levels as the construction bound, and once a list cost one level rather than two the two limits met: a too-deep chain of lists reported
NotImplementedErrorabout a type that never reaches a leaf instead ofValueErrorabout the depth. The frontend now descends one level further than the deepest schema construction accepts, so the bound that tripped is the bound that speaks. -
A union's
expectednames each branch the way that branch names itself when it fails alone, in place of the branch's node kind. A set of permitted strings — the commonest shape a field has — reportedone of: literal, literaland now reportsone of: the literal 'torch', the literal 'jax'; anEnumbranch names its class.Literal[...]builds a union of its constants, so its constants are what the message lists. The list is bounded at the same number of branches the closest-branch search reads and ends in...beyond it, so a wide union reports a readable prefix. -
The completeness probe searches refinements. Its schema universe crossed every other kind the decision procedure treats differently and held no refinement, so that whole fragment was outside the reach of the gate
docs/explanation/decidability.mdcites as the reason an unlisted conservative answer cannot go unnoticed. Four atoms — two order bounds and two regexes — put it in reach, and the four suspected gaps they surface are on the ledger with the route to deciding each. No answer changed; nothing was found unsound.
Deprecated¶
Validator.simplifyis deprecated and is removed in the next minor version. Calling it raises aDeprecationWarning. A schema is built in the lattice normal form, so the reduction it promises is the schema a caller already holds:reprshows it and==compares it. What it does beyond that is not a law but a decision — a meet of two provably disjoint kinds is the bottom, a join covering every region is the top — andis_empty,is_subtype_ofandis_equivalentdecide those and more without rewriting a term. Writeintersection(int, str).is_empty()rather thanrepr(intersection(int, str).simplify()) == "nothing".
open, close and ensure stay. The first two rewrite every record a schema
declares at any depth, inside its recursive definitions — a traversal that is
not spellable one set at a time, which is what a whole-schema operation is.
Fixed¶
- The extension imports on PyPy again. Telling a bare legacy alias
(
typing.List) from a parametrization with no arguments reached fortypes.GenericAliasthrough a binding whose type object is a CPython C-API static. That symbol is not part of the limited API and PyPy'scpyextdoes not export it, so the wheel built for PyPy failed to load — anundefined symbolat import, before any schema was built. The class is read from thetypesmodule instead, which is where every other special form this frontend recognizes is already read from, and which PyPy carries.
Only the PyPy wheels were affected; every CPython wheel imported and behaved the same throughout. A CI job now builds the extension for PyPy and imports it on every push, so the next such symbol fails there rather than in a release build.
- A relation is refuted only where the subject of that comparison has a value, at every level of it. A container's rule carries its element's refutation up, and the reading that says whether a refutation is a claim was taken once, about the whole subject -- so a list of an element with no value, which is the empty list and below a list of anything, was reported outside it. The reading is taken where the refutation is made:
from typing import Annotated, Never
import annotated_types as at
from valgebra import Validator
no_value = Annotated[list[Never], at.MinLen(1)]
small = Validator({"f": no_value})
large = Validator({"f": no_value, "g": int})
assert Validator(list[small]).is_subtype_of(Validator(list[large]))
The same held for a set, a repeated tuple, a record whose field is optional, and any nesting of those. Shapes whose own form names a value -- a scalar, a container that admits an empty one, a union with such a member -- are read without a descent, which is what keeps the reading's cost where it was.
- A sequence whose repeated element the rules cannot read is not refuted
against a fixed length.
tuple[X, ...] <= tuple[()]was refuted on the ground that a repeating tail cannot fit a fixed length, which stands only whereXhas a value: anXthe rules cannot decide may admit none, andtuple[X, ...]is then the empty tuple, which fits. The refutation is believed where the element is proven inhabited and declined where it is not, and the descriptor -- which reads the element -- decides the pair:
from typing import Annotated, Never
import annotated_types as at
from valgebra import Validator
no_value = Annotated[list[Never], at.MinLen(1)]
assert Validator(tuple[no_value, ...]).is_equivalent(Validator(tuple[()]))
Found by the law that holds the two deciders to one answer: the rules refuted an inclusion the sets prove.
- A schema disjoint from a meet is below that meet's complement.
A <= ~Basks whetherAandBshare a value, and the meet it built for that question heldBas a nested intersection where the rule that decides a meet empty compares the members of one intersection pairwise. Built through the meet constructor the members flatten, the pair meets, and the relation decides:
from valgebra import Validator, complement, intersection
small = Validator(int)
meet = intersection(Validator(str), Validator(bytes))
assert small.is_subtype_of(complement(meet))
The two deciders answered one question differently, which is what a disagreement between them looks like from outside: a relation that holds, reported as not proven.
-
Two wide literal unions are decided as sets. The core compares a union with a union member by member, so
intersection(Literal[*range(20_000)], Literal[*range(20_000, 40_000)]).is_empty()made one call into the bindings per pair of members. The bindings answer the whole disjointness question in one pass where they can hash the constants, and decline — leaving the member walk — where they cannot. -
A raised
ValidationErrorbuilds its structured model when something asks for it. Every failure became a dict, a path tuple and six attribute writes at raise time, so a report over 10,000 failing rows cost 26 ms whether or not the caller read a row; it is now 9 ms for a caller that logsstr(error), and still faster than before for one that readserrors. The attributes, their values andstr()are unchanged, and pickling builds the model first so what crosses a process boundary is the same plain data. -
import valgebracosts 0.9 ms, down from 32.__version__was read withimportlib.metadata.version(), which pullsemail,zipfile,inspectand the compression modules to read a file that says whatCargo.tomlalready said — 20 of those 32 milliseconds, and a dozen modules dragged into any process that imports valgebra. The extension carries the crate's version instead;tests/test_version.pyholds it to the installed distribution's. -
A bound against
nanis refused. Every comparison withnanis false, soAnnotated[float, Ge(nan)]admitted no value at all — the empty set written as a bound, which no caller means and which neither decider proves empty.MultipleOf(nan)goes the same way. A bound that is empty because the order says so, such asGt(inf), is kept: emptiness is then an answer. -
A container is refused as a
Literalargument, where it used to be read as a schema. The typing spec'sLiteraltakesNone, an enum member, or anint,bool,strorbytesvalue; Python does not reject the subscription, soLiteral[[1]]reached the constant fallthrough and came out aslist[Literal[1]], andLiteral[{}]as the empty record — sets the caller did not ask for, with no message saying so. A float is still accepted: it is not a spelling the spec allows either, but it is a constant, which this library pools like any other. A bareForwardRefis refused too, with the message a forward reference in a type argument already gave. -
A bare legacy typing alias is the class it aliases.
typing.Tuplewas read astuple[()]— the empty tuple, admitting()and nothing else — because a bare alias and a parametrization both carry no type arguments;typing.List,typing.Dictandtyping.Setwere refused for wanting one. Each is now its origin, soValidator(typing.Tuple) == Validator(tuple).tuple[()]keeps meaning the empty tuple, and a parametrized alias is unaffected. -
NotRequiredandRequiredare read underfrom __future__ import annotations. CPython computes aTypedDict's__required_keys__when the class is created, from the annotations as written — under PEP 563 those are strings, so the qualifier was invisible to it and every optional key in every module using the future import compiled as required, failing correct data withmissing_key. The resolved hint carries the qualifier and is now what answers, so a class means the same thing with the future import as without it. -
Two spellings of one schema print the same way. A union's members are ordered by the IR's own order and a literal sorts there by its pool slot -- the order the constants were first seen -- so
Literal[1, 2]andLiteral[2, 1]were one schema by==and byhashand two byrepr, againstdocs/guides/algebra.md's "reprshows it and==compares it". The literals in a union are now ordered by what they print; members that are not literals keep the place the normal form gives them. -
Two validators that differ only in a constant no longer share a hash.
__hash__skipped every pool slot, soLiteral[1]throughLiteral[1000]were one hash and a dictionary keyed by validators -- the reason the method exists -- degenerated into a linear scan, at 98 microseconds per lookup over ten thousand entries. The constant behind a slot is now folded in, which is 10,000 distinct hashes and 0.065 microseconds for the same registry. A constant with no hash contributes nothing, so a validator stays usable as a key whatever it pools. -
An integer key of any size reaches an error path as an integer, and so does a
bool.docs/guides/error-model.mdpromises a path a caller can walk back down to the value, and a key outside a machine word's range was rendered as itsrepr—'1180591620717411303424'— whileTruewas excluded outright and arrived as'True'. Both index nothing.d[True]andd[1]are one entry in Python, so aboolarrives as the integer it is. -
Explaining a failure over a large value no longer costs the size of the value. Every violation summarized the value it was about by building that value's whole
reprand keeping eighty characters of it, so a 20,000-deep list was rendered in full once per level of the walk: twelve seconds for a single error, against twenty microseconds foris_validon the same value. A container is now rendered under a bound instead, which is 1.1 ms for the same case and flat in the depth. A value small enough to print is unchanged. -
A class that holds its own validator is collected. A validator keeps the classes, enum members and callables its schema names, so
Model.validator = Validator(Model)is a reference cycle -- and the type was not tracked by the cycle collector, so the collector never saw the edge from the validator back to the class and every such class leaked. A validator now traverses the objects it owns, and can be weakly referenced, so a registry keyed by schema can be aWeakValueDictionaryand let its entries go. -
A relation over a pattern whose determinization is exponential refuses instead of exhausting memory.
Annotated[str, Regex("(a|b)*a(a|b){20}")]againstRegex("(a|b)*")spent six seconds and 668 MB, and two more repetitions aborted the process on a four-gigabyte allocation: the automaton bound was checked after the regex engine had built the whole dense table. The engine now carries the size limit, so the family answers in under 100 ms at any repetition count. Membership is unaffected — the walk runs the pattern, not the automaton — and a pattern that stays small is still decided. -
A
Flag, anIntFlagand anEnumwith no members are no longer read as the union of the members they list. A flag's|builds instances the class never listed, soValidator(Permission)was decided a subtype ofLiteral[Permission.READ, Permission.WRITE]althoughPermission.READ | Permission.WRITEis in the class and not in the literal; an enumeration with no members can still be subclassed, soValidator(Base)was decided a subtype ofnothingalthough a subclass's member is an instance of it. Each is now theisinstanceatom it was before the union reading existed, which leaves membership unchanged and the relations undecided. -
A list that changes size while it is being checked is reported as
mutated_during_validation, as a dict, a set and a record already were. A sequence is walked by position against a length read once, so a list grown by a predicate — or, on a free-threaded interpreter, by another thread — hid its new items from the walk, and one that shrank left the walk answering about items that were gone. In both directionsis_validreturnedTruefor a value that is not a member, andensurehanded that value back as checked. A tuple cannot be resized and keeps the plain iterator. -
A dict schema is not decided below the complement of a record it shares values with. Negating "no key of this part, other than the ones this atom names, maps anywhere" tightened that part's default, and a default governs every key the atom does not name — the excluded ones included — so a record complemented twice came back forbidding the key it is about, and
dict[str, int]was decided a subtype of~{"a": int}although{"a": 1}is in both. -
A numeric bound orders the booleans as well as the integers.
boolis a kind of its own to the set representation andintdenotes both, so a bound lowered as a set of integers alone denoted less than the schema does — and a smaller set has a larger complement, which is a subtype proof no value supports. A bound over a base that is not whole numbers,Annotated[float, Gt(0), Lt(1)]among them, is left to the structural rules rather than narrowed to integers. -
Two plain classes are not decided disjoint. A class built on no builtin lays down no instance layout of its own, and reading two such classes as laying down different layouts made them share no value — though
class Both(A, B)builds and its instances are in both. A layout conflict, which Python refuses to build a class across, still decides the pair. -
openandcloseare functions on sets.{"a?": nothing}and{}admit exactly the empty dict — the field allows the key to be absent and admits no value for it, which is what a closed record already says of every key it does not name — yet.open()gave them different sets. The redundant field is now read away first, so equal records open to equal records. Two consequences a caller may see:Validator({}).open()now admits every dict, where it used to be left alone (having no field never made{}a mapping — a clause and no field does), and a record carrying a field its own clauses already cover loses that field when opened or closed. -
A set reports its failing elements in an order the value fixes rather than the one the interpreter hands them over in, which moves with the hash seed. A set has no positions, so an element failure carries no index and only what it reports distinguishes it; the report is ordered by that, and
fail_fastkeeps the first of that order. The error model promised this determinism and a set was where it did not hold. -
A dict key that is not a string appears in an error path as its full
reprinstead of a summary cut at forty characters, and a string key appears whole. A path is what a caller walks back down to the value, and a truncated key indexes nothing. -
A refinement marker that would be dropped is refused instead. Four shapes silently produced a schema that admits either everything the marker excludes or nothing at all: a compiled
re.Pattern's flags were discarded, so a case-insensitive pattern refused the strings it matches; abytespattern and a length bound no length can equal were skipped entirely, leaving the base unconstrained; and a marker fromannotated_typesthat valgebra does not check, such asTimezoneorUnit, was ignored as if it were someone else's metadata.re.IGNORECASE,re.MULTILINE,re.DOTALLandre.VERBOSEare written into the pattern;re.ASCII,re.LOCALEandre.DEBUGare refused by name. Metadata from outside that vocabulary is still ignored, as the typing spec asks. -
A constraint no value of the base can answer is refused at build.
Annotated[int, MinLen(1)]asked an integer for its length, which raises, and a raise reads as a non-member — so the schema denoted nothing at all while looking like a narrowing. A constraint some value of the base can answer is unaffected: a union with a text branch, or a class that may define what the constraint asks for, still narrows. -
==on validators reads a pooled constant the wayLiteraldoes: same type and equal. Python's==runs across types, so comparing by equality alone madeValidator(Literal[1])andValidator(Literal[True])the same validator whileis_equivalentreported them disjoint — two answers about one pair. Comparing a validator with something else answersNotImplementedrather thanFalse, so the other operand gets its turn as the data model asks;==still falls back to identity, so the answer a caller sees is unchanged. -
A class is checked for the attributes it declares rather than for every annotation on it. A dataclass carrying an
InitVardenoted the empty set — the marker names a constructor parameter no instance keeps, so every instance was refused for a missing attribute — and one carrying aClassVarfailed to build at all. Both are read as what they are, a field declaredinit=Falseis still checked because the instance carries it, and aTypedDictfield qualifiedReadOnlycompiles to the type it qualifies instead of being refused. -
A string in the argument of a typing form is refused instead of read as a literal.
list["Account"]is a forward reference the typing spec resolves against the namespace the annotation was written in, and a runtime object carries no namespace; reading it as a constant built a list of the word, which refuses what the annotation admits.Validatorstill reads a bare constant as a literal wherever a value belongs — at the top level, in a native list or dict literal, and inLiteral[...]— and still resolves a class's own string annotations. -
An unpacked variadic tuple compiles to the shape it names.
tuple[int, *tuple[str, ...]]is a fixed prefix followed by a repeating tail — the same shapetuple[int, str, ...]spells — and it was read as a two-element tuple whose second element is a tuple, so it refused(1, "a")and admitted(1, ("a",)).Unpack[...]says the same thing and compiles the same way; an unpacked fixed tuple splices its elements in. An element after the repeating tail names a set the sequence node cannot carry and is refused, as is unpacking aTypeVarTuple, which binds no element types at runtime. -
The product-splitting rule builds its narrowed component through the schema constructors instead of writing at an index, so the double negation it used to manufacture — a complement of a branch component that is itself a complement — cancels where the rest of the tree says it does. The verdicts are unchanged; the rule stops producing a shape no other rule is written for.
-
A
MultipleOfdivisor of a different type than the value divides. The check reads the%operator rather than the value's__mod__alone, and half of what%means lives on the divisor: a value that does not know it answersNotImplemented, the divisor's__rmod__is asked next, andNotImplementedis truthy — so it read as a non-zero remainder.Annotated[int, MultipleOf(0.5)]refused every integer, and aFractionorDecimaldivisor refused every value. -
A
recursivedefinition nested inside another resolves its self-reference wherever the build put it. An inner fixpoint whose body names the outer variable compiles to a definition of its own, and the outer marker lands in that definition rather than in the outer body — so resolving the body alone left the marker dangling, and a dangling marker matches no value: the schema silently rejected members. Contractivity is checked over the whole system of definitions for the same reason, which refusesX = ~XandX = X | list[Y]written across a nesting; both built before and denoted no fixpoint. -
A placeholder kept past the
recursivebuilder it was handed to is refused at construction. The placeholder is an ordinary validator, so nothing stops a caller storing it, and what it stands for stops existing when the builder returns; using one afterwards built a validator that admitted no value and said nothing about why. -
A container that changes size while it is being checked is reported as
mutated_during_validationinstead of aborting the interpreter. Membership runs Python at almost every entry of a dict or a set — a predicate, an__eq__, anisinstancehook — and a free-threaded interpreter lets another thread write to a shared value meanwhile; the iterators underneath both containers answer that with a panic, which crosses the boundary as aBaseExceptionno caller catches as a validation failure. The walk reads both containers in a way that survives the change and reports a non-member, because a reading cut short decides nothing about the contents. Only a change in size costs the reading: a value rewritten in place is unaffected. The same code reports a value whose two readings disagree, which is the same failure of the check to have a stable value to decide about. -
The membership walk counts the levels it holds open and refuses past 512 of them with
recursion_limit, so a value inside every published construction bound cannot exhaust the native stack. Counting recursive unfoldings alone does not bound the frames: an unfolding descends the whole definition body, so a body at the schema-depth bound turns the 128 permitted unfoldings into thousands of frames. A recursive schema over a deep body meets the level bound and reports it; a linked list at the unfolding bound is unaffected, because the level ceiling sits above what that shape asks for. -
ValidationErrorcan be pickled, so a validation failure crosses a process boundary with its structured model intact. The exception's__module__was a bare_valgebra, which names no importable module, andpicklelocates a class by that string together with the qualified name — so a worker in a process pool or a task queue delivered aPicklingErrornaming an internal module instead of the validation result. The module is nowvalgebra, the package the name is exported from: it is baked into every serialized error, so it has to be the path that keeps resolving rather than the private extension underneath, whose name this reference reserves the right to change. A traceback and areprreadvalgebra.ValidationErrorfor the same reason.
0.0.9 - 2026-08-26¶
Two Annotated markers were read as something other than what they mean, and
both produced a schema that denoted nothing or its complement. No other decision
changes.
Fixed¶
- A marker that is itself callable is asked, and only one that is not is
taken apart by its
.func.annotated_types.Predicatecarries its callable there and is not callable, which is why the attribute is read at all — butNotandfunctools.partialcarry one too.
Not(f) denotes the values where f is false, and it defines __call__
because calling is what applies the negation. Read by its .func it
constrained by f instead, so every value under it got the opposite verdict:
Annotated[int, Not(is_even)] admitted the even numbers.
partial(eq, 1) lost its bound argument the same way and became eq, which
raises when called with a single value, so the schema admitted nothing at all.
Callability is the discriminator annotated_types itself encodes, so this is
its rule rather than a heuristic.
- A class in
Annotatedmetadata is ignored, as the typing spec asks of metadata a consumer does not recognize. A marker carries its values on an instance and a class carries the descriptors that read them:Ge(0)holdsge = 0, whileGeholds the slot descriptor, and reading that as a bound built a comparison no value is ordered against. A class is also callable, and calling one constructs rather than asks — a unit marker written as a class answered no question and refused every value. Both traps ended in a schema denoting nothing.
Every other callable is still a predicate: a function, a lambda, a bound
method, an object with __call__.
Changed¶
-
The documentation pages are numbered, so a page's URL carries its number:
/03-schema-language/where it was/schema-language/. The site's landing page is unchanged. -
The published benchmark figures are re-measured, and the performance page now records the interpreter build its baseline was measured on rather than only the version: a free-threaded CPython runs this work about twice as slow as a GIL build of the same version. The ratios are unchanged — 7.6x on deep nesting, 2.0x on the wide record, 1.8x on the large array — and no decision or code path moved.
0.0.8 - 2026-08-25¶
Membership costs less on a refined schema, and no decision or message changes.
Changed¶
- A violation's message is built when a violation is recorded rather than on
every check. Naming a bound takes the bound's
repr, and a value that belongs produces no violation to name it in, so accepting a value used to cost the size of the schema's operand rather than the size of the value.
Per-check cost over the bare type, release build, median of eleven runs of fifty thousand: a single comparison bound about 16 ns where it was about 123, and two about 29 where they were about 258. A comparison bound therefore costs less than a call into a Python predicate, which is the ordering the refinements page describes. The absolute figures are one machine's and move by around a tenth between runs; the ratio and the ordering are what travel.
The operand's size no longer enters into it. A passing check against
Annotated[str, Ge(s)] measures about 51 ns for a one-character s and about
52 ns for a two-hundred-thousand-character one, against 143 ns and 303 us.
Every violation carries the message it carried, and every decision is unchanged.
- The pages carry four things a reader could otherwise only find by experiment.
The
Regexdialect is the Rust engine's, notre's, and a pattern both engines accept can match different strings — POSIX bracket expressions, Unicode case folding of the Turkish dotless i, and\p{...}property escapes, so compiling successfully is not a test of which language a pattern is in. The depth budget accounts for refinements: a refinement is a node, so it costs a level on top of whatever it narrows, and the marker it carries makes no difference. A map can constrain some keys and leave the rest free by giving the permissive clause the complement of the claimed keys, whereopenadmits a clause matching every key and so subsumes a narrower one. And the decidability boundary records that a meet of two distinct literals is not decided empty, with no sound rule to close it: a literal's equality is the value's own, so two literals can share a member while neither contains the other.
0.0.7 - 2026-08-25¶
Fixed¶
-
open,close, andsimplifyrewrite a validator's recursive definitions as well as its root. A recursive validator's root is a single back edge and every record, union, and refinement it declares lives in the definitions table, so all three were no-ops on exactly the schemas that carry the most structure:recursive(lambda n: {"a": int, "next": n}).open()admitted no undeclared key, andsimplifyleft a recursive body unreduced. -
The frontend descends as far as the construction bounds publish, so a schema those bounds accept is no longer rejected while being compiled. Sets, dicts, and records nest to the documented limit rather than to 100 levels, and the message a rejection carries reports how far the frontend descended rather than naming a cause it cannot know.
Added¶
-
is_emptydecides an interval that skips every integer however the meet is spelled.intersection(Annotated[int, Gt(0)], Annotated[int, Lt(1)])is empty, asAnnotated[int, Gt(0), Lt(1)]already was: an intersection is a subset of each of its members, so a member bounded to the integers bounds the whole meet. Aboolbase counts integers for the same reason, since it subclassesint. -
is_subtype_ofdecides attribute schemas across a class hierarchy. A dataclass or named tuple is below one over a base class whose every attribute it carries with a narrower schema, and below the bare class it is an instance of.
Both are conservative-to-decided moves: every relation that held in 0.0.6 still holds, and each carries the counter-direction that keeps it from over-firing.
Changed¶
-
openandclosemay raiseValueError. Opening a record adds a catch-all clause, so it grows the schema and the construction bounds apply to what it produces; a validator near the node limit can cross it. -
A union of no members reprs as
nothingand a meet of none asanything, because each constructor owns the identity of its own arity.repr(union())was the empty string, which is not an expression that rebuilds the validator. -
A widening between two eight-member literal unions costs 619 ns where it cost 1.66 us, and a union of opaque members decides up to about eight hundred members where it decided up to four hundred. The lattice bound asking whether a supertype covers the universe reads that supertype's region set instead of building the complement of a deep clone of it, and the emptiness folds stop once no later member can change the verdict.
-
Membership costs what it cost. The competitive baseline in the performance page is re-measured with its spread and the method that produced it: against pydantic in strict mode, 7.6x on a schema nested twenty-five deep, 2.1x on a fifty-field closed record, and 1.8x on a flat array of ten thousand integers.
On upgrade, handle ValueError from open and close where a schema is built
in a loop, and expect a recursive validator to answer as the recursion says it
should rather than as its root alone did. Nothing else changes.
0.0.6 - 2026-08-08¶
Changed¶
- Internal only, with no change to what any schema admits or answers: the schema
IR's purely structural walks share one declaration of each node's child
schemas, and the two index remappings applied when validators compose —
appending a constants pool, or interning one into another — share one walk over
one set of payload sites. Every public method returns what it returned in
0.0.5, and validation,
is_empty, the error model,repr, and every compiled form are unchanged.
Nothing to do on upgrade. The version exists so the reorganization ships under a release of its own rather than inside one whose entries describe something else.
0.0.5 - 2026-08-08¶
Added¶
tests/test_completeness_probe.py, which searches for relations answeredFalsethat no value in a wide universe refutes, and fails when one appears that is not written down with a reason. Every other instrument could only notice a completeness gap someone had already thought of; this one searches.
Fixed¶
-
is_subtype_ofdecides a closed record against a catch-all mapping:{"x": int}is recognized belowdict[str, int]. The closed record had a dispatch branch of its own that read a field the supertype covers through a catch-all as undecided, though the general keyed-map rule beside it already decided exactly that. One rule serves every keyed-map shape. -
is_subtype_ofdecides inclusion in a complement:Ais below~Bwhen the two share no value, solist[int]is recognized below~intanddict[str, int]below~str. There was no rule for a complement on the right at all, so the relation was decided only when the left side was itself a complement.
Both change a public method's answer from False to True. No relation that
answered True can answer False, and validation, is_empty, compilation and
every rendered form are unchanged.
is_subtype_ofandis_equivalentdecide the lattice bounds by emptiness rather than by the shape of the atom. A schema that denotes the empty set without being spellednothing— a record with an uninhabited required field, a canceling intersection — is recognized as a subtype of every schema, and one that covers the universe without being spelledanythingis recognized as a supertype of every schema. Both previously answeredFalse, which was sound but incomplete.
This changes the answer of a public method from False to True for those
schemas. Nothing else moves: is_empty, validation, compilation and every
rendered form are unchanged, and no relation that answered True can answer
False. The gap was masked whenever the other side was scalar, because the
region check decides that case correctly, so it was only visible against a
container, a record, an instance or typing.Any.
0.0.4 - 2026-07-13¶
Added¶
- The schema construction bounds are published as module constants —
MAX_SCHEMA_DEPTH,MAX_DEFINITIONS, andMAX_SCHEMA_NODES— so a caller can size a schema against them.
Changed¶
- Schema construction is bounded on every growth path, not only the combinator
operators: the
Validatorconstructor, the|operator,union,intersection,complement,recursive, andsimplifyall reject a schema past a fixed nesting depth, recursive-definition count, or total node count with aValueError.simplifycan therefore raise when negation-normal form expands a schema past the size bound (seedocs/guides/limits.md). - The project describes its schema algebra as closed under its operations rather than complete.
Fixed¶
- No sequence of public calls can overflow the native stack or exhaust memory
while building a validator. A schema grown too deep through the
Validatorconstructor orrecursive, or too large by combining a validator with itself in a loop, is rejected at construction instead of crashing the interpreter on a later clone, drop, decision, or render. This extends the 0.0.3 composition bound, which rejected only the combinator operators and left the constructor andrecursivepaths unbounded. Annotated[int, MultipleOf(0)]is rejected when the validator is compiled: no value is a multiple of zero, so the unsatisfiable schema raises aValueErrorat construction instead of rejecting every value through a swallowedZeroDivisionErrorat validation time.
0.0.3 - 2026-07-07¶
Added¶
- Schema composition bounds nesting depth: combining validators with
|,union,intersection, orcomplementpast a fixed depth is rejected at construction with aValueError, so a schema grown in an unbounded loop cannot overflow the native stack on its next check. Arecursiveback edge counts as a leaf, so a recursive schema's depth stays finite (seedocs/guides/limits.md). - The type stub declares the
__copy__and__deepcopy__methods a compiled validator exposes.
Fixed¶
- Release builds report a well-formed validation error instead of panicking across the boundary when the error builder is handed no failures, and the per-element sequence walk folds an impossible missing-schema case to a non-member result rather than a panic.
0.0.2 - 2026-06-30¶
Added¶
valgebra.__version__exposes the installed distribution version, read from the package metadata that maturin derives from the Cargo workspace manifest.
0.0.1 - 2026-06-29¶
The first published release. valgebra ships to PyPI as prebuilt wheels across the support matrix.
Added¶
- Compile-once / validate-fast engine:
Validator(schema)builds an immutable validator withvalidate(raises),is_valid(bool fast path), andensure. - Typing-annotation frontend: scalars,
None,Any,list/set/frozenset/dict, fixed, variadic, and prefix-plus-tail tuples (tuple[A, B, ...]), unions andOptional,Literal,TypedDict, dataclasses,NamedTuple, enums, runtime-checkable protocols,NewType, PEP 695 aliases, andAnnotatedrefinements (with bounds, length, and predicate constraints). - Native forms: a list literal as a sequence —
[T], the fixed[A, B], and the prefix-plus-tail[A, B, ...](a fixed prefix then a repeated tail); a dict literal as a closed record ("key?"optional); a single{KeyType: ValueType}entry as a mapping; and any constant as a typed literal. - A closed Boolean algebra:
union,intersection,complement,anything,nothing, and a law-justifiedsimplify, with the lattice laws property-tested. Conditional fields and key cardinality are composed from these (documented recipes), not shipped as combinators. - Set-relation queries on a compiled validator:
is_subtype_of(set inclusion),is_equivalent(mutual inclusion), andis_empty(an unsatisfiable schema, including a recursive schema with no base case). Decided soundly across scalars, containers, records and mappings, sequence forms, class subtyping (issubclass), and literal values (by membership), and conservative on the cases it cannot prove. - Recursive schemas via the
recursivefixpoint, with cycle and depth guards. - A structured, machine-readable error model: aggregated failures, opt-in fail-fast, and closest-branch reporting for unions.
- JSON input on the Rust path:
validate_json,is_valid_json, andload(validate and return the parsed value), consistent with the object path and faster than parse-then-validate. - A stable
reprthat renders a schema back to its annotation form. - Thread-safe, immutable validators.
- A performance program: criterion and pytest-benchmark suites, a recorded baseline against pydantic-core and jsonschema, and a deterministic instruction-count CI regression gate.