Skip to content

aiollm.serialization

serialization

JSON codec, value formatting and request value normalization.

Modules:

Name Description
json

JSON codec used by default, backed by orjson.

normalize

Conversion of request values into wire-ready values.

protocols

Interfaces of request value encoding.

traversal

One guard against cycles and deep nesting for every value traversal.

values

Encoding of single request values: dates, durations and scalars.

Classes:

Name Description
IValueFormatter

Turns dates, times and durations into the text an API expects.

BaseValueFormatter

Writes dates, times and durations in ISO 8601.

Functions:

Name Description
dumps

Serialize data to JSON.

loads

Parse JSON.

IValueFormatter

Bases: Protocol

Turns dates, times and durations into the text an API expects.

A method declares one in __value_formatter__; every part of the request (body, form, query and path) goes through it, so a value is written the same way wherever it is sent.

Methods:

Name Description
format_datetime

Write a moment in time.

format_date

Write a calendar date.

format_time

Write a time of day.

format_timedelta

Write a duration.

format_datetime

format_datetime(value: datetime) -> str

Write a moment in time.

Parameters:

Name Type Description Default
value datetime

The datetime to write.

required

Returns:

Type Description
str

Its text.

format_date

format_date(value: date) -> str

Write a calendar date.

Parameters:

Name Type Description Default
value date

The date to write.

required

Returns:

Type Description
str

Its text.

format_time

format_time(value: time) -> str

Write a time of day.

Parameters:

Name Type Description Default
value time

The time to write.

required

Returns:

Type Description
str

Its text.

format_timedelta

format_timedelta(value: timedelta) -> str

Write a duration.

Parameters:

Name Type Description Default
value timedelta

The duration to write.

required

Returns:

Type Description
str

Its text.

BaseValueFormatter

Writes dates, times and durations in ISO 8601.

This is the format of date-time, date and time in JSON Schema and OpenAPI, and the one Pydantic writes in JSON: a UTC moment as 2026-01-02T03:04:05Z, another offset as +03:00, a duration as PT30S. A provider whose API wants another format subclasses it and overrides the methods it needs.

Methods:

Name Description
format_datetime

Write a moment in time in ISO 8601.

format_date

Write a calendar date in ISO 8601.

format_time

Write a time of day in ISO 8601.

format_timedelta

Write a duration in ISO 8601.

format_datetime

format_datetime(value: datetime) -> str

Write a moment in time in ISO 8601.

Parameters:

Name Type Description Default
value datetime

A timezone-aware datetime.

required

Returns:

Type Description
str

Its text, such as 2026-01-02T03:04:05Z.

Raises:

Type Description
ValueError

If the datetime is naive: the moment it names depends on the clock of whoever reads it.

format_date

format_date(value: date) -> str

Write a calendar date in ISO 8601.

Parameters:

Name Type Description Default
value date

The date to write.

required

Returns:

Type Description
str

Its text, such as 2026-01-02.

format_time

format_time(value: time) -> str

Write a time of day in ISO 8601.

Parameters:

Name Type Description Default
value time

The time to write, with or without an offset.

required

Returns:

Type Description
str

Its text, such as 12:00:00 or 12:00:00Z.

format_timedelta

format_timedelta(value: timedelta) -> str

Write a duration in ISO 8601.

Parameters:

Name Type Description Default
value timedelta

The duration to write.

required

Returns:

Type Description
str

Its text, such as PT30S or -PT30S.

dumps

dumps(data: Any) -> bytes

Serialize data to JSON.

Parameters:

Name Type Description Default
data Any

A JSON-compatible value.

required

Returns:

Type Description
bytes

UTF-8 encoded JSON.

loads

loads(data: bytes | str) -> Any

Parse JSON.

Parameters:

Name Type Description Default
data bytes | str

JSON text or UTF-8 encoded bytes.

required

Returns:

Type Description
Any

The decoded value.

Raises:

Type Description
JSONDecodeError

If data is not valid JSON. It is a subclass of ValueError.