jschon.json

class jschon.json.JSON(value, *, parent=None, key=None, itemclass=None, pre_recursion_args=None, **itemkwargs)

An implementation of the JSON data model.

__bool__()

Return bool(self).

Return type:

bool

__delitem__(index)

Delete self[index].

Supported for JSON types array and object.

Parameters:

index (int | str) –

Return type:

None

__eq__(other)

Return self == other.

Parameters:

other (JSON | None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) –

Return type:

bool

__ge__(other)

Return self >= other.

Supported for JSON types number and string.

Parameters:

other (JSON | int | float | str) –

Return type:

bool

__getitem__(index)

Return self[index].

Supported for JSON types array and object.

Parameters:

index (int | slice | str) –

Return type:

JSON

__gt__(other)

Return self > other.

Supported for JSON types number and string.

Parameters:

other (JSON | int | float | str) –

Return type:

bool

__init__(value, *, parent=None, key=None, itemclass=None, pre_recursion_args=None, **itemkwargs)

Initialize a JSON instance from the given JSON-compatible value.

The parent, key, pre_recursion_args, itemclass and itemkwargs parameters should typically only be used in the construction of compound JSON documents by JSON subclasses.

The use of the parent, key, itemclass, and itemkwargs parameters can be customized in subclasses by overriding instantiate_sequence() and instantiate_mapping(), for example if some child elemnts need to be instances of a different class than others. Child elements instantiated in this way should still be instances of itemclass through inheritance, and itemkwargs should be respected if at all possible.

Parameters:

  • value (None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) – a JSON-compatible Python object

  • parent (JSON | None) – the parent node of the instance

  • key (str | None) – the index of the instance within its parent

  • pre_recursion_args (Dict[str, Any] | None) – arguments to pass to pre_recursion_init() during construction

  • itemclass (Type[JSON] | None) – the JSON subclass used to instantiate child nodes of arrays and objects (default: JSON)

  • itemkwargs (Any) – keyword arguments to pass to the itemclass constructor

__iter__()

Return iter(self).

Supported for JSON types array and object.

Return type:

Iterator

__le__(other)

Return self <= other.

Supported for JSON types number and string.

Parameters:

other (JSON | int | float | str) –

Return type:

bool

__len__()

Return len(self).

Supported for JSON types string, array and object.

Return type:

int

__lt__(other)

Return self < other.

Supported for JSON types number and string.

Parameters:

other (JSON | int | float | str) –

Return type:

bool

__repr__()

Return repr(self).

Return type:

str

__setitem__(index, obj)

Set self[index] to obj.

Supported for JSON types array and object.

Parameters:

  • index (int | str) –

  • obj (JSON | None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) –

Return type:

None

__str__()

Return str(self).

Return type:

str

add(path, obj)

Add obj at path relative to self.

The JSON equivalent to add(), this method performs an in-place JSON Patch add operation on self.

If path is empty, the value of self is replaced by obj.

Experimental.

Parameters:

  • path (str | JSONPointer) –

  • obj (JSON | None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) –

Return type:

None

copy(from_, to)

Not yet implemented; experimental.

Parameters:
Return type:

None

dumpf(path)

Serialize the instance data to a JSON file.

Parameters:

path (str | PathLike) – the path to the file

Return type:

None

dumps()

Serialize the instance data to a JSON string.

Return type:

str

insert(index, obj)

Insert obj before index.

Supported for JSON type array.

Parameters:

  • index (int) –

  • obj (JSON | None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) –

Return type:

None

instantiate_mapping(value)

Recursively instantiate JSON objects.

By default, instantiate elements as itemclass instances, passing itemkwargs in addition to the parent and key.

Parameters:

value (Mapping[JSONCompatible]) –

Return type:

Mapping[JSON]

instantiate_sequence(value)

Recursively instantiate JSON arrays.

By default, instantiate elements as itemclass instances, passing itemkwargs in addition to the parent and key.

Parameters:

value (Sequence[None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]]) –

Return type:

Sequence[JSON]

classmethod loadf(path, **kwargs)

Deserialize a JSON file to a JSON instance.

Parameters:

  • path (str | PathLike) – the path to the file

  • kwargs (Any) – keyword arguments to pass to the JSON (subclass) constructor

Return type:

JSON

classmethod loadr(url, **kwargs)

Deserialize a remote JSON resource to a JSON instance.

Parameters:

  • url (str) – the URL of the resource

  • kwargs (Any) – keyword arguments to pass to the JSON (subclass) constructor

Return type:

JSON

classmethod loads(value, **kwargs)

Deserialize a JSON string to a JSON instance.

Parameters:

  • value (str) – the JSON string

  • kwargs (Any) – keyword arguments to pass to the JSON (subclass) constructor

Return type:

JSON

move(from_, to)

Not yet implemented; experimental.

Parameters:
Return type:

None

pre_recursion_init(**kwargs)

Initialization code run between parent and child initialization.

Subclasses that need to run code after the basic attributes of this node and its parant nodes have been initialized, but before child nodes are initialized, should override this method and pass its arguments trhough the pre_recursion_args parameter to the constructor.

Parameters:

kwargs (Any) –

Return type:

None

remove(path)

Remove the instance at path relative to self.

The JSON equivalent to remove(), this method performs an in-place JSON Patch remove operation on self.

If path is empty, the value of self is set to None.

Experimental.

Parameters:

path (str | JSONPointer) –

Return type:

None

replace(path, obj)

Set obj at path relative to self.

The JSON equivalent to replace(), this method performs an in-place JSON Patch replace operation on self.

If path is empty, the value of self is replaced by obj.

Experimental.

Parameters:

  • path (str | JSONPointer) –

  • obj (JSON | None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) –

Return type:

None

test(path, obj)

Not yet implemented; experimental.

Parameters:

  • path (str | JSONPointer) –

  • obj (JSON | None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]) –

Return type:

None

data: None | bool | int | float | str | List[JSON] | Dict[str, JSON]

The instance data.

JSON type

data type

null

None

boolean

bool

number

int | float

string

str

array

list[JSON]

object

dict[str, JSON]
property document_root: JSON
itemclass: Type[JSON]

The JSON class type of child instances.

itemkwargs: Dict[str, Any]

Keyword arguments to the itemclass constructor.

key: str | None

The index of the instance within its parent.

parent: JSON | None

The containing JSON instance.

property path: JSONPointer

Return the path to the instance from the document root.

type: str

The JSON type of the instance. One of null, boolean, number, string, array, object.

property value: None | bool | int | float | str | Sequence[Any] | Mapping[str, Any]

Return the instance data as a JSON-compatible Python object.

jschon.json.JSONCompatible

Type hint for a JSON-compatible Python object.

alias of Union[None, bool, int, float, str, Sequence[Any], Mapping[str, Any]]

jschon.json.false = False

Use to represent the JSON false value literally in Python code.

jschon.json.null = None

Use to represent the JSON null value literally in Python code.

jschon.json.true = True

Use to represent the JSON true value literally in Python code.