viat.support.json ¶

Python type hints for JSON values.

These initially used a protocol re-implementation of some stdlib collection ABCs (see 1). Unfortunately, after going through several compatibility problems with both the corresponding ABCs and with actual collections, we decided to split the type hints from the classes used for instance checks.

• Runtime type checking must be done via isinstance(value, JsonArray). Using value: JsonArray would not allow lists to be assigned (see 2).

• Static type checking must be done via the annotation value: JsonArrayT. Using isinstance(value, JsonArrayT) produces a TypeError (see 3).

Note that isinstance(value, JsonArray) cannot be mimicked using isinstance(value, Sequence) because the latter also matches strings.

Mutable JSON objects introduce additional complications because of the (in)variance of the type parameters of MutableMapping, so we abandoned them entirely.

We hope that, at some point, Python's type ecosystem is flexible enough to support JSON hints.

43
44
45
46
47
48

class JsonArray(Sequence['JsonT'], abc.ABC):
    """An ABC for immutable JSON arrays.

    This is intended to be used for instance checks. For type hints,
    consider using [`JsonArrayT`][..JsonArrayT] instead.
    """

62
63
64
65
66
67

class JsonObject(Mapping[str, 'JsonT'], abc.ABC):
    """An ABC for immutable JSON objects.

    This is intended to be used for instance checks. For type hints,
    consider using [`JsonObjectT`][..JsonObjectT] instead.
    """