JSON

One process-wide codec for every Stario JSON operation: responses.json, Datastar signal read and patch, telemetry formatters, and TestClient (r.json() and request encoding). Import it as import stario.json as stario_json.

The default is StdlibJsonCodec. It emits compact UTF-8 JSON (ensure_ascii=False, allow_nan=False, separators (",", ":")). dumps() returns text. dumps_bytes() returns UTF-8 bytes. loads() accepts text, bytes, or a byte array.

Stario uses bytes for HTTP and SSE, and text for HTML attributes and telemetry storage. A byte-native codec only decodes when a caller asks for dumps().

This module is transport configuration. Application models and validation stay in application code.

Replace the codec

Call set_codec() during setup, before bootstrap yields. A later call replaces the codec for operations that have not started. Stario does not synchronize replacement with in-flight requests or telemetry writes.

import msgspec

import stario.json as stario_json

class MsgspecCodec:

    def dumps(self, value, *, default=None):

        return self.dumps_bytes(value, default=default).decode()

    def dumps_bytes(self, value, *, default=None):

        return msgspec.json.encode(value, enc_hook=default)

    def loads(self, data):

        return msgspec.json.decode(data)

stario_json.set_codec(MsgspecCodec())

orjson has a native byte path, so dumps_bytes does not encode text first:

import orjson

import stario.json as stario_json

class OrjsonCodec:

    def dumps(self, value, *, default=None):

        return self.dumps_bytes(value, default=default).decode()

    def dumps_bytes(self, value, *, default=None):

        return orjson.dumps(value, default=default)

    def loads(self, data):

        return orjson.loads(data)

stario_json.set_codec(OrjsonCodec())

Codec contract

A replacement must implement JsonCodec:

• dumps(value).encode("utf-8") and dumps_bytes(value) are the same bytes.

• Both forms are one compact RFC 8259 JSON value: no byte-order mark, no formatting line breaks.

• Dump methods raise TypeError or ValueError when serialization fails.

• loads raises ValueError when the input is not valid JSON.

default is forwarded. Each backend decides which native types it handles before it calls that function. Datetime, UUID, Decimal, and model types may serialize inside the backend.