THE ORIONIS API
Build with clarity.
Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.
Compile bounded rule plans and collect nested validation failures.
| Class | _ |
Retain trusted field names and local rules for one native Struct. |
| Function | _build |
Compile under a reentrant lock, including recursive schema graphs. |
| Function | _cache |
Read and promote a bounded validation plan. |
| Async Function | _collect |
Validate nested schemas, including schemas held inside collections. |
| Async Function | _collect |
Execute a pre-resolved validation plan against a schema instance. |
| Function | _collection |
Resolve the element annotation selected from a concrete collection type. |
| Function | _compile |
Build and cache the custom-rule execution plan for a schema. |
| Function | _field |
Select executable rules from a field's validated metadata. |
| Function | _schema |
Compile immutable rule traversal for declared transport data. |
| Function | _type |
Check an annotation for nested schemas requiring traversal. |
| Async Function | _validate |
Apply local schema rules once across converted transport data. |
| Function | _visit |
Visit each declared Struct once, including recursive references. |
| Function | _warm |
Eagerly populate _PLAN_CACHE for any nested Orionis schema type. |
| Constant | _BUILDING |
Building used by rules_executor. |
| Constant | _EMPTY |
Shared empty mapping returned for schemas without Orionis metadata. Reused instead of allocating a fresh dict on every plan build. |
| Constant | _PLAN |
Plan cache used by rules_executor. |
| Constant | _PLAN |
Cache of validation plans for schema types. Keys are schema classes; values are tuples of field validation plans as returned by _build_plan(). Populated on demand by _build_plan and warmed at class creation time. |
| Constant | _PLAN |
Synchronization primitive controlling access to plan lock. |
Read and promote a bounded validation plan.
| Parameters | |
klass:type | Schema class whose validation plan is requested. |
| Returns | |
tuple | None | Cached validation plan, or None when the schema is not cached. |
Validate nested schemas, including schemas held inside collections.
| Parameters | |
value:object | Nested schema or collection held by the parent field. |
prefix:str | Dot-terminated path prefix already qualified with the parent field. |
failures:list | Accumulator receiving every ValidationFailure found. |
| Returns | |
None | No return value. |
tuple, instance: object, prefix: str, failures: list):
(source)
¶
Execute a pre-resolved validation plan against a schema instance.
This function is the true hot path. It takes the plan as a parameter so that callers who already hold it (e.g. Schema.validate) skip the cache lookup and the type() call. Every failure is accumulated so the caller can report all of them at once.
| Parameters | |
plan:tuple | Non-empty plan produced by _build_plan for this instance's type. |
instance:object | Schema instance to validate. |
prefix:str | Dot-terminated path prefix for nested field names, e.g. "address." so that child fields report "address.zip". Pass "" at the top level. |
failures:list | Accumulator receiving every ValidationFailure found. |
| Returns | |
None | No return value. |
Build and cache the custom-rule execution plan for a schema.
| Parameters | |
klass:type | Schema class whose msgspec fields and __orionis_meta__ metadata are inspected. |
| Returns | |
tuple | Entries of (encoded_name, dotted_prefix, getter, validators, is_nested). Omit fields and descendants with no custom rules. |
| Raises | |
TypeError | Raised when field metadata contains an object that is neither a Rule instance nor supported validation metadata. |
type, field_name: str, items: Iterable[ object]) -> tuple[ Rule, ...]:
(source)
¶
Select executable rules from a field's validated metadata.
| Parameters | |
klass:type | Schema owning the field. |
fieldstr | Name used in metadata error messages. |
items:collections.abc.Iterable[object] | Declared rule and documentation metadata. |
| Returns | |
tuple[orionis.schemas.rule.Rule, ...] | Rules in their declaration order. |
| Raises | |
TypeError | If an item is neither a rule nor supported metadata. |
Compile immutable rule traversal for declared transport data.
| Parameters | |
annotation:object | Trusted scalar, Struct, union or collection annotation. |
| Returns | |
collections.abc.Mapping[type, orionis.schemas.rules_executor._SchemaPlan] | Plans owned by the caller's compiled declaration, not a global cache. |
Check an annotation for nested schemas requiring traversal.
| Parameters | |
tp:object | Type annotation to inspect. May be a plain type or wrapped in Union/|, Annotated or a collection. |
rulesbool, optional | Exclude child schemas with an empty cached rule plan when True. |
| Returns | |
bool | Whether a direct, collection or union member is an Orionis schema satisfying the rules_only filter. |
Apply local schema rules once across converted transport data.
| Parameters | |
value:object | Converted value whose native types and constraints already passed. |
plans:collections.abc.Mapping[type, orionis.schemas.rules_executor._SchemaPlan] | Immutable traversal plans compiled from the declared annotation. |
| Returns | |
None | No return value. |
| Raises | |
orionis.schemas.exceptions.ValidationException | If a declared schema violates a framework rule. |
Eagerly populate _PLAN_CACHE for any nested Orionis schema type.
Called from _build_plan to warm nested validation while capacity allows. Evicted child plans are rebuilt on demand during later validation.
| Parameters | |
tp:object | Field type annotation, potentially an Annotated type, Union or collection, or a bare class. |
| Returns | |
None | No return value. |
Shared empty mapping returned for schemas without Orionis metadata. Reused instead of allocating a fresh dict on every plan build.
| Value |
|