JSON

stario.json is one process-wide codec used by w.json, Datastar signal read and patch, telemetry formatters, and TestClient. Import it as import stario.json as stario_json.

The default uses the standard library and 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 encoder only decodes when a caller asks for dumps().

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

Replace the codec#

set_codec() takes two functions — the library’s own functions plug in directly. Call it 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

stario_json.set_codec(msgspec.json.encode, msgspec.json.decode)

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

import orjson

import stario.json as stario_json

stario_json.set_codec(orjson.dumps, orjson.loads)

Codec contract#

The codec is a JsonEncode/JsonDecode pair:

• encode returns one compact RFC 8259 JSON value as text or UTF-8 bytes: no byte-order mark, no formatting line breaks. Stario converts once where it needs the other form.

• encode raises TypeError or ValueError for an unsupported value. A backend may serialize its native datetime, UUID, Decimal, or model types.

• decode accepts text, bytes, or a byte array and raises ValueError when the input is not valid JSON.

• Both must be safe to call from any thread.

Deprecated: passing a codec object to set_codec(), the JsonCodec protocol, StdlibJsonCodec, and the default= parameter on dumps()/dumps_bytes() are deprecated and will be removed in 6.0. An application codec must serialize custom types itself before encoding.