intellicrack.core.json_payload

Type narrowing for decoded JSON payloads.

Every value that arrives from json.loads(), an HTTP response body or a raw JSON Schema is statically an object. A bare isinstance(value, dict) narrows it to dict[Unknown, Unknown], because the check proves nothing about the key or value types, and that partial unknown then propagates through every expression downstream.

JSON itself does carry that guarantee: an object always has string keys, and its members are always JSON values. The predicates here state that guarantee once, as typing.TypeIs, so a caller narrows straight to a usable type in both the positive and the negative branch and nothing downstream is unknown.

JsonArray

A decoded JSON array.

alias of list[Any]

JsonObject

A decoded JSON object.

Keys are always strings; values are JSON values.

alias of dict[str, Any]

as_json_array(value)[source]

Return a decoded JSON value as an array, or None if it is not one.

Parameters:: value (object) – The value to convert.
Returns:: value narrowed to a JSON array, or None when it is any other kind of JSON value.
Return type:: JsonArray | None

as_json_object(value)[source]

Return a decoded JSON value as an object, or None if it is not one.

Parameters:: value (object) – The value to convert.
Returns:: value narrowed to a JSON object, or None when it is any other kind of JSON value.
Return type:: JsonObject | None

copy_json(value)[source]

Copy a JSON value, however deeply it nests.

copy.deepcopy() recurses once per level and fails past the interpreter’s recursion limit; this walk is iterative.

Parameters:: value (object) – The JSON value to copy.
Returns:: A new value equal to value sharing no container with it.
Return type:: object

is_json_array(value)[source]

Check whether a decoded JSON value is an array.

Parameters:: value (object) – The value to test, typically straight out of a decoded payload.
Returns:: True when value is a list, narrowing it to JsonArray for the caller.
Return type:: TypeIs[JsonArray]

is_json_object(value)[source]

Check whether a decoded JSON value is an object.

Parameters:: value (object) – The value to test, typically straight out of a decoded payload.
Returns:: True when value is a mapping, narrowing it to JsonObject for the caller.
Return type:: TypeIs[JsonObject]

json_array_at(container, key)[source]

Read one key of a JSON object, requiring the member to be an array.

Parameters:

container (dict[str, Any]) – The JSON object to read from.
key (str) – The member name.

Returns:

The member narrowed to a JSON array, or None when the key is absent or the member is another kind of value.

Return type:

JsonArray | None

json_equality_key(value)[source]

Build the text under which JSON Schema equality becomes string equality.

JSON Schema compares numbers by value, so 1 and 1.0 are equal, but keeps booleans apart from numbers, so true and 1 are not; arrays compare in order and objects without regard to member order. Python’s own == gets the booleans wrong, and neither lists nor dicts can be hashed. The key is canonical JSON text – members sorted by name, integral numbers written as integers – so equal keys mean equal JSON values, and since a string hashes, comparing n values for duplicates takes n steps rather than n squared. Both the walk and the key are flat, so no nesting depth is too deep.

Parameters:: value (object) – The JSON value.
Returns:: Its key.
Return type:: str

json_object_at(container, key)[source]

Read one key of a JSON object, requiring the member to be an object.

Parameters:

container (dict[str, Any]) – The JSON object to read from.
key (str) – The member name.

Returns:

The member narrowed to a JSON object, or None when the key is absent or the member is another kind of value.

Return type:

JsonObject | None

json_str_at(container, key)[source]

Read one key of a JSON object, requiring the member to be a string.

Parameters:

container (dict[str, Any]) – The JSON object to read from.
key (str) – The member name.

Returns:

The member when it is a string, or None when the key is absent or the member is another kind of value.

Return type:

str | None

map_json_strings(value, rename)[source]

Apply a string mapping to every object key and every string in a JSON value.

The walk is iterative, so a value nested far deeper than the interpreter’s recursion limit is mapped as surely as a flat one.

Parameters:

value (object) – The JSON value to map.
rename (Callable[[str], str]) – Maps one string, key or member, to its replacement.

Returns:

A new value of the same shape. When two keys of one object map to the same string, the later member wins at the earlier position.

Return type:

object