ORIONIS API REFERENCE

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.

module documentation

Compile bounded rule plans and collect nested validation failures.

Class _SchemaPlan Retain trusted field names and local rules for one native Struct.
Function _build_plan Compile under a reentrant lock, including recursive schema graphs.
Function _cache_get Read and promote a bounded validation plan.
Async Function _collect_nested Validate nested schemas, including schemas held inside collections.
Async Function _collect_with_plan Execute a pre-resolved validation plan against a schema instance.
Function _collection_item_type Resolve the element annotation selected from a concrete collection type.
Function _compile_plan Build and cache the custom-rule execution plan for a schema.
Function _field_rules Select executable rules from a field's validated metadata.
Function _schema_plans Compile immutable rule traversal for declared transport data.
Function _type_contains_nested Check an annotation for nested schemas requiring traversal.
Async Function _validate_schemas Apply local schema rules once across converted transport data.
Function _visit_schema_plan Visit each declared Struct once, including recursive references.
Function _warm_child_plan Eagerly populate _PLAN_CACHE for any nested Orionis schema type.
Constant _BUILDING Building used by rules_executor.
Constant _EMPTY_META Shared empty mapping returned for schemas without Orionis metadata. Reused instead of allocating a fresh dict on every plan build.
Constant _PLAN_CACHE Plan cache used by rules_executor.
Constant _PLAN_CACHE_MAX 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_LOCK Synchronization primitive controlling access to plan lock.
def _build_plan(klass: type) -> tuple: (source)

Compile under a reentrant lock, including recursive schema graphs.

Parameters
klass:typeSchema class whose validation plan is requested.
Returns
tupleCompiled and cached validation plan for the schema.
def _cache_get(klass: type) -> tuple | None: (source)

Read and promote a bounded validation plan.

Parameters
klass:typeSchema class whose validation plan is requested.
Returns
tuple | NoneCached validation plan, or None when the schema is not cached.
async def _collect_nested(value: object, prefix: str, failures: list): (source)

Validate nested schemas, including schemas held inside collections.

Parameters
value:objectNested schema or collection held by the parent field.
prefix:strDot-terminated path prefix already qualified with the parent field.
failures:listAccumulator receiving every ValidationFailure found.
Returns
NoneNo return value.
async def _collect_with_plan(plan: 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:tupleNon-empty plan produced by _build_plan for this instance's type.
instance:objectSchema instance to validate.
prefix:strDot-terminated path prefix for nested field names, e.g. "address." so that child fields report "address.zip". Pass "" at the top level.
failures:listAccumulator receiving every ValidationFailure found.
Returns
NoneNo return value.
def _collection_item_type(tp: object, selector: str) -> object | None: (source)

Resolve the element annotation selected from a concrete collection type.

Parameters
tp:objectUnwrapped collection annotation.
selector:strSequence index or dictionary key.
Returns
object | NoneElement annotation, or None for an incompatible selector.
def _compile_plan(klass: type) -> tuple: (source)

Build and cache the custom-rule execution plan for a schema.

Parameters
klass:typeSchema class whose msgspec fields and __orionis_meta__ metadata are inspected.
Returns
tupleEntries of (encoded_name, dotted_prefix, getter, validators, is_nested). Omit fields and descendants with no custom rules.
Raises
TypeErrorRaised when field metadata contains an object that is neither a Rule instance nor supported validation metadata.
def _field_rules(klass: type, field_name: str, items: Iterable[object]) -> tuple[Rule, ...]: (source)

Select executable rules from a field's validated metadata.

Parameters
klass:typeSchema owning the field.
field_name:strName 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
TypeErrorIf an item is neither a rule nor supported metadata.
def _schema_plans(annotation: object) -> Mapping[type, _SchemaPlan]: (source)

Compile immutable rule traversal for declared transport data.

Parameters
annotation:objectTrusted 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.
def _type_contains_nested(tp: object, *, rules_only: bool = False) -> bool: (source)

Check an annotation for nested schemas requiring traversal.

Parameters
tp:objectType annotation to inspect. May be a plain type or wrapped in Union/|, Annotated or a collection.
rules_only:bool, optionalExclude child schemas with an empty cached rule plan when True.
Returns
boolWhether a direct, collection or union member is an Orionis schema satisfying the rules_only filter.
async def _validate_schemas(value: object, plans: Mapping[type, _SchemaPlan]): (source)

Apply local schema rules once across converted transport data.

Parameters
value:objectConverted 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
NoneNo return value.
Raises
orionis.schemas.exceptions.ValidationExceptionIf a declared schema violates a framework rule.
def _visit_schema_plan(hint: object, plans: dict[type, _SchemaPlan], schema_type: type[msgspec.Struct]): (source)

Visit each declared Struct once, including recursive references.

Parameters
hint:objectTrusted field or parameter annotation.
plans:dictPlans owned by the current compilation.
schema_type:typeBase class supplying native local validation rules.
Returns
NoneNo return value.
def _warm_child_plan(tp: object): (source)

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:objectField type annotation, potentially an Annotated type, Union or collection, or a bare class.
Returns
NoneNo return value.
_BUILDING: set[type] = (source)

Building used by rules_executor.

Value
set()
_EMPTY_META: dict[str, list[object]] = (source)

Shared empty mapping returned for schemas without Orionis metadata. Reused instead of allocating a fresh dict on every plan build.

Value
{}

Plan cache used by rules_executor.

Value
OrderedDict()
_PLAN_CACHE_MAX: int = (source)

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.

Value
1024
_PLAN_LOCK = (source)

Synchronization primitive controlling access to plan lock.

Value
RLock()