duron.codec module
A codec converts application values to JSON for persistence and reconstructs them when read. Select a codec on the workflow; its effects and ports use the same codec.
Default codec
DefaultCodec encodes finite JSON values and returns decoded JSON unchanged.
It accepts None, bool, int, finite float, str, lists of JSON values,
and dictionaries with string keys. Tuples, bytes, dates, dataclasses, and model
objects require a custom codec. NaN and infinities are rejected, including
inside containers. Only exact built-in JSON types are accepted; subclasses such
as enums need a custom codec. Strings must be valid UTF-8. Cyclic containers,
nesting beyond 64 container levels, and integers exceeding 4096 bits are rejected.
Type validation
The default codec itself does not validate annotations or reconstruct Python
types. The runtime wraps the selected codec with checks at workflow, effect,
and port boundaries. Values must match their declared types. Missing annotations
and Any allow arbitrary values supported by the codec.
Codec.decode_json is generic: given TypeHint[T], it must return T or
raise if it cannot decode the value. Duron validates decoded values and checks
that encoded values can be decoded to the declared type before committing them.
A custom codec must reconstruct external data as needed; its decoder can run
during encoding and must be free of external side effects. Validation checks
type conformance, not equality of the original and reconstructed objects.
Implement a custom codec
A codec must encode every value it handles as finite JSON and reconstruct values according to the supplied type hint. Select one codec on the workflow; it handles workflow and effect arguments and results and port payloads. Duron handles its own runtime metadata separately.
from dataclasses import dataclass
from typing import TypeVar, cast
import duron
from duron.codec import DefaultCodec, JSONValue, TypeHint
T = TypeVar("T")
@dataclass(frozen=True)
class Order:
number: str
class OrderCodec:
def encode_json(
self, value: object, annotated_type: TypeHint[object], /
) -> JSONValue:
if isinstance(value, Order):
return {"number": value.number}
return DefaultCodec.encode_json(value, annotated_type)
def decode_json(self, encoded: JSONValue, expected_type: TypeHint[T], /) -> T:
if expected_type is Order:
if not isinstance(encoded, dict) or not isinstance(
encoded.get("number"), str
):
raise TypeError("invalid encoded order")
return cast(T, Order(encoded["number"]))
return DefaultCodec.decode_json(encoded, expected_type)
@duron.workflow(codec=OrderCodec())
async def echo(ctx: duron.WorkflowContext, order: Order) -> Order:
return order
async def example() -> None:
async with duron.SQLiteScheduler(":memory:", workflows=[echo]) as scheduler:
for _ in range(2):
run = await scheduler.submit(echo, "order", Order("A-1"))
assert await run.result() == Order("A-1")
This codec handles an Order as a directly annotated value. Supporting
list[Order], unions, or nested models requires recursive handling of those
type hints; the fallback to DefaultCodec does not add it.
Evolve a codec
Effects can be reused by workflows with different codecs. Make decode_json accept previously persisted wire values as the format
evolves, using in-band version tags when needed. Duron does not fingerprint
codec implementations. Choose a new workflow name and run ID for incompatible
changes.
Remote adapters must preserve the active workflow's serialization contract.
Encode failure details
For structured failure details, explicitly encode a value with the codec and
pass the JSON to ApplicationError(..., details=...). When catching the error,
decode error.details with the application schema. Exception objects are never
passed to the workflow codec.
Serialization contracts: the Codec protocol and the default JSON codec.
Codec
Protocol for encoding/decoding Python objects to/from JSON-serializable values.
Implement this protocol to provide custom serialization for types not supported
by the default codec (e.g., dataclasses, Pydantic models, custom objects).
Select it on the workflow to encode application values throughout that run.
Runtime framing uses fixed JSON. Incompatible encoding changes require a
new workflow name. Decoding must return the type described by the
supplied hint or raise; workflow code trusts this generic contract. The
codec can be used explicitly for structured ApplicationError.details.
Runtime error metadata uses fixed JSON; exception objects are never passed
to the codec.
decode_json
encode_json
Convert a Python object to a JSON-serializable value for persistence.
Parameters:
-
result(object) –The object to encode (e.g., operation result or argument)
-
annotated_type(TypeHint[object]) –Type hint for the object's type
Returns:
-
JSONValue–A JSON-serializable value (None, bool, int, float, str, list, or dict)
Raises:
-
TypeError–If the object cannot be serialized
DefaultCodec
Encode finite JSON values and return decoded values unchanged.
Supports None, booleans, numbers, strings, lists, and dictionaries with
string keys. Annotations do not trigger type validation or reconstruction.
Use a custom Codec for other Python types.
_is_json_value
Return whether x is a finite, canonical JSON-serializable value.
Only exact builtin types qualify, so enum and other subclasses are rejected rather than silently decoded as their base type. Strings must be valid UTF-8 (no lone surrogates), integers are bounded, nesting is limited to a fixed depth, and cyclic containers are rejected.
Returns: