Static checkers¶
What a static type checker reads from a validator, which schema spellings it refuses and what to write instead, and the ruff settings a project that validates its own classes needs. valgebra checks values at runtime and a checker never runs it: the package's type stub is what the two share, and ty, mypy and pyright read it alike except where a table below says otherwise.
A validator's type is its set's¶
Validator is generic: Validator[T] is a validator whose members a checker
reads as Ts. The constructor reads a class as the type it names, and a True
from is_valid narrows the value it was asked about:
from dataclasses import dataclass
from typing import assert_type
from valgebra import Validator
@dataclass
class Point:
x: int
y: int
points = Validator(Point)
assert_type(points, Validator[Point])
def as_point(value: object) -> Point | None:
if points.is_valid(value):
return value # a checker reads `value` as a `Point` here
return None
assert as_point(Point(0, 0)) == Point(0, 0)
assert as_point((0, 0)) is None
What each spelling reads as:
| Schema | A checker reads the validator as |
|---|---|
a class: int, a dataclass, list[int], tuple[int, str], a TypedDict |
Validator of that type |
| a compiled validator | its own type |
None |
Validator[None] |
a Protocol, runtime-checkable or not |
the protocol under ty and pyright; object under mypy |
a NewType |
the new type under mypy; object under ty and pyright |
int \| None, Optional[int], Literal[...], Annotated[...] |
Validator[object] |
a dict or list literal, a constant, a value typed object |
Validator[object] |
a generic type alias applied, Pair[int] |
Validator[object]: the stub has no overload for an alias, and Validator(tuple[int, int]) is what reads as its body |
Any |
gradual: Any under mypy, Unknown under ty, object under pyright |
a \| b for two typed validators |
the union of their types |
a class \| a validator, int \| v |
Validator[object] under ty; under mypy and pyright a types.UnionType, on which a validator method is an error. Write the validator on the left: v \| int |
union(a, b) for validators of one type |
that type; for two types ty reads their union, mypy and pyright object |
intersection, complement, recursive |
Validator[object] |
instance_of(C) |
Validator[C], the type isinstance narrows to; an abstract class object under mypy |
A typed reading is not a buildable one. The first row reads any class
subscripted as Validator of it, and some of those are refused when built:
Sequence[int], deque[int], type[int] and a user generic such as Box[int]
type-check and raise NotImplementedError at the call, as
the forms the schema language does not list
do. The instance_of row is read the same way: instance_of(TD) for a
TypedDict type-checks as Validator[TD] and raises TypeError at the call,
as instance_of of a Protocol does, since neither class has instances of its
own (the class alone).
The rows that name a checker are held by tests/test_checker_readings.py, which
runs all three over one fixture per row under tests/typing/readings/ and
compares what each reveals, at the versions the project locks: a checker release
that reads a row differently fails that test when the lock takes it, and this
table moves with it.
Where the set has no static type, the validator reads as object. A meet,
a complement and a fixpoint have no static spelling. int | None, a Literal
and an Annotated form have one, but they are type expressions rather than
classes, and a stub reads them only through PEP 747's TypeForm. The stub does
not use it yet: ty reports an error at a TypeForm overload for any argument
that is not a type expression -- a schema held in a variable typed object
among them -- where the typing spec's overload rules say to try the next one.
On a Validator[object], is_valid answers a plain bool and ensure
returns its argument as the argument's own type.
A True narrows, and a False does not¶
is_valid is a TypeGuard, so it narrows only when it answers True. A
refusal is no evidence that a value lies outside the static type, because the
static type is often wider than the set:
from valgebra import Validator
assert not Validator(float).is_valid(1) # a checker's `float` admits `1`
assert not Validator(complex).is_valid(1.0) # and its `complex` admits `1.0`
A TypeIs would let a checker conclude from each False above that the value
is not a float, or not a complex, and read the code that runs next as
unreachable. The same holds wherever the check reads more than the class: a
dataclass instance whose field holds a value outside the field's type is
refused, and is still an instance. On a typed validator ensure and load
return the type:
Validator(Point).ensure(value) is a Point, and a TypedDict's validator
loads a document as that TypedDict.
Write a parameter bare¶
A parameter that takes any validator is written Validator, which is
Validator[Any]:
from valgebra import Validator
def admits(schema: Validator, value: object) -> bool:
return schema.is_valid(value)
assert admits(Validator(int), 1)
assert not admits(Validator({"name": str}), {})
Validator[object] takes only a validator whose set reads as object. The
parameter is invariant, because that is what lets the stub answer a bool on an
untyped validator and a narrowing on a typed one, so a Validator[int] is not
a Validator[object]. At runtime Validator[int] is a types.GenericAlias, so
an annotation that is evaluated finds it; it is not a schema, and
Validator(Validator[int]) is refused.
Spellings a checker refuses, and what to write instead¶
Each pair builds one schema, and the second spelling is the one ty, mypy and pyright accept.
| Written | Why a checker refuses it | Write instead |
|---|---|---|
tuple[str, int, ...] |
... is legal only as the second of two arguments |
tuple[str, *tuple[int, ...]] |
Literal[1.5], Literal[obj] |
Literal takes an int, str, bytes or bool value, an enum member or None |
the constant itself: Validator(1.5), union(1.5, "a"); a callable obj is the exception, refused bare, and Literal[fn] is its one spelling, which a checker reports |
list[v], dict[str, v] for a validator v |
a variable is not a type expression | the native forms [v] and {str: v} |
{"name": str} where a type is expected |
a dict literal is not a type expression | a TypedDict class |
count: v for a validator v, as a class field |
a variable is not a type expression | count: Annotated[T, v], for a T holding every member of v: a checker reads T |
tuple[int, v] for a validator v |
a variable is not a type expression | tuple[int, Annotated[object, v]]: Annotated[object, v] is v |
from typing import Annotated
from valgebra import Validator, union
v = Validator(int)
assert Validator(tuple[str, *tuple[int, ...]]).is_valid(("x", 1, 2))
assert union(1.5, "a").is_valid(1.5)
assert Validator([v]).is_valid([1, 2])
assert Validator({str: v}).is_valid({"a": 1})
assert Validator(Annotated[int, v]) == v
assert Validator(tuple[int, Annotated[object, v]]).is_valid((1, 2))
The ruff settings a validated class needs¶
[tool.ruff.lint.flake8-type-checking]
runtime-evaluated-decorators = ["dataclasses.dataclass"]
runtime-evaluated-base-classes = [
"typing.TypedDict",
"typing.NamedTuple",
"typing_extensions.TypedDict",
"typing_extensions.NamedTuple",
]
[tool.ruff.lint.flake8-bugbear]
extend-immutable-calls = [
"valgebra.Validator",
"valgebra.union",
"valgebra.intersection",
"valgebra.complement",
"valgebra.recursive",
"valgebra.instance_of",
]
The first table keeps a field's class importable when the validator is
built. A dataclass, TypedDict or NamedTuple is read through
typing.get_type_hints at Validator(...), so every class its fields name has
to be importable then. ruff's TC001 to TC003 move an import that only an
annotation uses under if TYPE_CHECKING:, and in a module with
from __future__ import annotations the Validator(...) call then raises
NameError. Naming the decorator and the base classes whose annotations are
read at runtime keeps those imports where they are; typing_extensions'
spellings are separate names and need their own entries. On Python 3.15 ruff
makes such an import lazy instead, and the frontend resolves a lazily imported
class.
The second table accepts a validator as a shared default. B008 and
RUF009 flag a call written as a function's default argument or a dataclass
field's default, because the value is built once and shared. A validator is
immutable and hashable, so one built there is the intended shared value.
What this does not cover¶
- A checker's type is an upper bound, not the set, except at a signature.
Validator(Point)reads asPointand admits only the points whose fields are members too; nothing here makes a checker run the validator. A callable is checked for being callable and no more (a callable is not looked inside), so where the type names a signature the set is wider than the type: a protocol with a method, or a class with a field typedCallable[[int], float], admits a value whose method or field takes other arguments. Under ty and pyright aTruefromis_validnarrows that value to the protocol, and the call the protocol promises can raiseTypeError; mypy reads a protocol's validator asValidator[object]and narrows nothing. - An editor shows the types, not the prose. The stub carries no docstrings,
as a stub does by convention (ruff's
PYI021); the prose is on the compiled objects, wherehelp()reads it, and on the API reference. - The readings are the locked checkers'. A caller on another release of ty, mypy or pyright may read a row differently until the project's lock reaches it.