yera.typing.serialisation

Pydantic-based serialization utilities for enhanced type support.

Symbols

def canonicalise_json — Normalize a JSON payload into Yera's canonical representation.
def deserialise — Deserialise a JSON string or bytes into a Python object per the type hint.
def serialise — Serialise a value to JSON using the given type hint.
def serialise_runtime_value — Serialize a heterogeneous runtime value to JSON.
def serialise_value — Derive and serialize a supported runtime value.
class SerialisedValue — A runtime value serialized with its derived type information.
def type_schema — Return the serialization schema for a supported declared type.

canonicalise_json

canonicalise_json(
    payload: bytes | str,
) → str

Normalize a JSON payload into Yera's canonical representation.

Parameters

payload
type: bytes | str

JSON text to parse and normalize.

Returns

type: str

Compact JSON with deterministic object-key ordering.

Raises

ValueError

If the payload is not valid finite JSON.

deserialise

deserialise(
    raw: bytes | str,
    type_hint: type,
) → object

Deserialise a JSON string or bytes into a Python object per the type hint.

Parameters

raw
type: bytes | str

The JSON-encoded data (bytes or str).

type_hint
type: type

The target type annotation.

Returns

type: object

The deserialised Python object.

Raises

TypeError

If type_hint is not supported.

ValueError

If deserialisation fails.

serialise

serialise(
    value: object,
    type_hint: type,
) → bytes | str

Serialise a value to JSON using the given type hint.

Parameters

value
type: object

The Python object to serialise.

type_hint
type: type

The type annotation guiding serialisation.

Returns

type: bytes | str

A JSON-encoded byte string.

Raises

TypeError

If type_hint is not supported.

serialise_runtime_value

serialise_runtime_value(
    value: object,
) → str

Serialize a heterogeneous runtime value to JSON.

Unlike type-derived serialization, this function supports empty and heterogeneous nested collections whose complete type cannot be inferred from their runtime contents. Supported leaf values are serialized through Yera's normal typing infrastructure.

This representation is intended for display and model-context transport. It does not retain sufficient type information for deserialization back into every original Python container type.

Parameters

value
type: object

A runtime value containing Yera-supported leaves.

Returns

type: str

Compact JSON containing the normalized runtime value.

Raises

TypeError

If the value contains a leaf unsupported by Yera's typing infrastructure.

ValueError

If a supported leaf cannot be serialized.

serialise_value

serialise_value(
    value: object,
) → SerialisedValue

Derive and serialize a supported runtime value.

Parameters

value
type: object

A populated runtime value accepted by Yera's typing system.

Returns

type: SerialisedValue

The derived type information, serialized payload, and JSON Schema.

Raises

TypeError

If the value's supported type cannot be derived.

ValueError

If the value does not conform to its derived type.

SerialisedValue

A runtime value serialized with its derived type information.

Attributes

type_hint
type: type

The supported Yera type derived from the runtime object.

type_name
type: str

Human-readable rendering of the derived type.

payload
type: str

JSON produced by Yera's serialization infrastructure.

schema
type: dict[str, object]

Serialization-mode JSON Schema for the derived type.

type_schema

type_schema(
    type_hint: type,
) → dict[str, object]

Return the serialization schema for a supported declared type.

Parameters

type_hint
type: type

The declared type whose schema should be generated.

Returns

type: dict[str, object]

A JSON Schema describing the serialized representation.

Raises

TypeError

If the declared type is not supported.