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

Prepare explicitly coercible values without changing the source payload.

Function _coerce_array Normalize declared array fields without consuming the discriminator tag.
Function _coerce_collection Prepare collection values while preserving keys and fixed tuple positions.
Function _coerce_mapping Normalize selected mapping entries without changing their source.
Function _coerce_union Preserve compatible union branches and normalize only matching structures.
Function _coerce_value Normalize a selected annotation before applying any value constraints.
Function _expand_struct_sequence Expand existing struct items and leave native input representations intact.
Function _field_plan Cache fields requiring coercion or struct expansion and their wire positions.
Function _plain_struct_item Select uniform struct items whose fields need no further preparation.
Function _requires_preparation Find coercion markers or struct types requiring instance revalidation.
Function coerce_payload Prepare marked values and existing structs using copy-on-write containers.
def _coerce_array(payload: list | tuple, plan: tuple[tuple[str, int, object], ...], *, enabled: bool) -> object: (source)

Normalize declared array fields without consuming the discriminator tag.

Parameters
payload:list | tuplePositional schema input.
plan:tuple[tuple[str, int, object], ...]Encoded field names, indices and target annotations.
enabled:boolWhether an enclosing marker enables every field.
Returns
objectUpdated positional input or the original sequence.
def _coerce_collection(value: object, annotation: object, *, enabled: bool) -> object: (source)

Prepare collection values while preserving keys and fixed tuple positions.

Parameters
value:objectInput collection or incompatible value left for validation.
annotation:objectCollection annotation declaring its item types.
enabled:boolWhether an enclosing marker enables every collection value.
Returns
objectPrepared collection, or the unchanged input.
def _coerce_mapping(payload: Mapping[object, object], entries: Iterable[tuple[object, object, object]], *, enabled: bool) -> object: (source)

Normalize selected mapping entries without changing their source.

Parameters
payload:Mapping[object, object]Original mapping copied only when a value changes.
entries:Iterable[tuple[object, object, object]]Keys, current values and target annotations to normalize.
enabled:boolWhether an enclosing marker enables every selected value.
Returns
objectUpdated mapping or the original input when no values change.
def _coerce_union(value: object, annotation: object, *, enabled: bool) -> object: (source)

Preserve compatible union branches and normalize only matching structures.

Parameters
value:objectUnion input to prepare.
annotation:objectDeclared union and its branch metadata.
enabled:boolWhether an enclosing marker enables every branch.
Returns
objectPrepared branch value or unchanged incompatible input.
def _coerce_value(value: object, annotation: object, *, enabled: bool) -> object: (source)

Normalize a selected annotation before applying any value constraints.

Parameters
value:objectValue to normalize.
annotation:objectDeclared type, possibly annotated, nested or a union.
enabled:boolWhether an enclosing marker already enabled coercion.
Returns
objectConverted value or input retained for standard error reporting.
def _expand_struct_sequence(value: list | tuple | set | frozenset, schema: type[msgspec.Struct]) -> object: (source)

Expand existing struct items and leave native input representations intact.

Parameters
value:list | tuple | set | frozensetHomogeneous collection copied only when an instance needs expansion.
schema:type[msgspec.Struct]Item type with no descendant coercion or struct preparation.
Returns
objectOriginal collection or a copy containing expanded instance payloads.
@lru_cache(maxsize=1024)
def _field_plan(schema: type[msgspec.Struct], *, enabled: bool) -> tuple[tuple[str, int, object], ...]: (source)

Cache fields requiring coercion or struct expansion and their wire positions.

Parameters
schema:type[msgspec.Struct]Schema whose fields are prepared.
enabled:boolWhether an enclosing marker enables every field in this schema.
Returns
tuple[tuple[str, int, object], ...]Encoded names, positional indices and field annotations.
def _plain_struct_item(origin: type, args: tuple[object, ...]) -> type[msgspec.Struct] | None: (source)

Select uniform struct items whose fields need no further preparation.

Parameters
origin:typeCollection origin used to distinguish fixed and variadic tuples.
args:tuple[object, ...]Collection type arguments, already extracted by the caller.
Returns
type[msgspec.Struct] | NoneUniform struct type with an empty preparation plan, if applicable.
def _requires_preparation(annotation: object) -> bool: (source)

Find coercion markers or struct types requiring instance revalidation.

Parameters
annotation:objectField, collection item or union annotation to inspect.
Returns
boolWhether conversion requires coercion or expansion of existing structs.
def coerce_payload(payload: object, schema: type[msgspec.Struct], *, enabled: bool = False) -> object: (source)

Prepare marked values and existing structs using copy-on-write containers.

Existing struct constructors and mutations bypass native validation, so expand those instances before the final conversion. Unmarked scalar fields remain strict and schemas without preparation retain their original inputs.

Parameters
payload:objectInput mapping, positional data or existing schema instance.
schema:type[msgspec.Struct]Schema declaring the target types and coercion metadata.
enabled:bool, optionalWhether an enclosing marker enables all descendant fields.
Returns
objectPrepared payload, or the original value when no changes are needed.