JSON Typing API¶

Module for typing and typechecking JSON

This module offers functions for introspecting the JSON types of python object representing JSON, including those created with @jsonable, as well as typechecking JSON values against type hints.

class pheres._typing.JsonableValue¶

Bases: abc.ABC, pheres._utils.Virtual

Virtual class to represent a jsonable value in type hints.

While this ABC does implements __subclasshook__(), it should not be used with issubclass. Use the is_jsonable_value function instead

class pheres._typing.JsonableArray¶

Bases: abc.ABC, pheres._utils.Virtual

Virtual class to represent a jsonable array in type hints.

While this ABC does implements __subclasshook__(), it should not be used with issubclass. Use the is_jsonable_array function instead

class pheres._typing.JsonableDict¶

Bases: abc.ABC, pheres._utils.Virtual

Virtual class to represent a jsonable dict in type hints.

While this ABC does implements __subclasshook__(), it should not be used with issubclass. Use the is_jsonable_dict function instead

class pheres._typing.JsonableObject¶

Bases: abc.ABC, pheres._utils.Virtual

Virtual class to represent a jsonable object in type hints.

While this ABC does implements __subclasshook__(), it should not be used with issubclass. Use the is_jsonable_object function instead

pheres._typing.JSONValue¶

Type hint for JSON values (as defined in the JSON specification)

alias of Union[None, bool, int, float, str, pheres._typing.JsonableValue]

pheres._typing.JSONArray¶

Type hint for JSON Arrays (as defined in the JSON specification)

alias of Union[List[JSONType], pheres._typing.JsonableArray]

pheres._typing.JSONObject¶

Type hint for JSON Object (as defined in the JSON specification)

alias of Union[Dict[str, JSONType], pheres._typing.JsonableDict, pheres._typing.JsonableObject]

pheres._typing.JSONType¶

Type hint for any JSON

alias of Union[None, bool, int, float, str, pheres._typing.JsonableValue, List[JSONType], pheres._typing.JsonableArray, Dict[str, JSONType], pheres._typing.JsonableDict, pheres._typing.JsonableObject]

pheres._typing.normalize_hint(tp: TypeHint)¶

Normalize a JSON type hint

Parameters: tp – JSON type hint to normalize
Returns: a normalized representation of tp
Raises: TypeHintError – when tp or an inner type is not a valid JSON type

pheres._typing.is_json_type(type_hint: TypeHint) → bool ¶

Check that the type_hint is valid for JSON

Supports JSONable subclasses. Implemented by calling normalize_json_type() and catching TypeHintError

Parameters: type_hint – type hint to test
Returns: True if the type hint is valid for JSON, false otherwise

pheres._typing.find_collision(ltp: TypeHint, rtp: TypeHint) → bool ¶

Finds a JSON common for the two type hints, or return MISSING

The type hints must be in normalized form

Parameters

ltp – left type hint
rtp – right type hint

Returns

value, such that typecheck(value, ltp) and typecheck(value, rtp) or MISSING if no such value exists

pheres._typing.is_number(obj: Any) → bool ¶

Test if the JSON object is a JSON number

Parameters: obj – object to test the type of
Returns: True if obj is a json number, False otherwise

pheres._typing.is_value(obj: Any) → bool ¶

Test if the JSON object is a JSON value

Parameters: obj – object to test the type of
Returns: True if obj is a json value, False otherwise

pheres._typing.is_array(obj: Any) → bool ¶

Test if the JSON object is a JSON Array

Parameters: obj – object to test the type of
Returns: True if obj is a json array, False otherwise

pheres._typing.is_object(obj: Any) → bool ¶

Test if the JSON object is a JSON Object

Parameters: obj – object to test the type of
Returns: True if obj is a json Object, False otherwise

pheres._typing.is_json(obj: Any) → bool ¶

Check if a python object is valid JSON

Only tuples and lists are accepted for JSON arrays. Dictionary must have string as keys

Parameters: obj – object to test
Returns: True if obj is a valid json, False otherwise
Raises: CycleError – the value has circular references

pheres._typing.is_jsonable_value(obj: Any) → bool ¶: Return True if obj is a jsonable value

pheres._typing.is_jvalue_class(cls: Any) → bool ¶: Return True if cls is a jsonable value class

pheres._typing.is_jvalue_instance(obj: Any) → bool ¶: Return True if obj a jsonable value instance

pheres._typing.is_jsonable_array(obj: Any) → bool ¶: Return True if obj is a jsonable array

pheres._typing.is_jarray_class(cls: Any) → bool ¶: Return True if cls if a jsonable array class

pheres._typing.is_jarray_instance(obj: Any) → bool ¶: Return True if obj is a jsonable array instance

pheres._typing.is_jsonable_dict(obj: Any) → bool ¶: Return True if obj is a jsonable dict

pheres._typing.is_jdict_class(cls: Any) → bool ¶: Return True if cls is a jsonable dict class

pheres._typing.is_jdict_instance(obj: Any) → bool ¶: Return True if obj is a jsonable dict instance

pheres._typing.is_jsonable_object(obj: Any) → bool ¶: Return True if obj is a jsonable object

pheres._typing.is_jobject_class(cls: Any) → bool ¶: Return True if cls is a jsonable object class

pheres._typing.is_jobject_instance(obj: Any) → bool ¶: Return True if obj is a jsonable object instance

pheres._typing.is_jsonable(obj: Any) → bool ¶: Return True if obj is a jsonable value or an instance of a jsonable value

pheres._typing.is_jsonable_class(cls: Any) → bool ¶: Return True if cls is a jsonable class

pheres._typing.is_jsonable_instance(obj: Any) → bool ¶: Return True if obj is a jsonable instance

pheres._typing.typeof(obj: JSONType) → TypeHint¶

Return the type alias of the type of the passed JSON object.

For nested types such as list or dict, the test is shallow and only checks the container type.

Parameters: obj – object to get the type of
Returns: JSONValue, JSONArray or J`SONObject` based on the type of the passed object
Raises: JSONValueError – the passed object is not a valid JSON

Attention

The returned value is a type hint, equality testing must be done with Identity comparisons:

typeof({}) == JSONObject # undefined

typeof({}) is JSONObject # True

pheres._typing.typecheck(value: JSONType, tp: TypeHint) → bool ¶

Test if a JSON value matches a JSON type hint

The type hint must be normalized (see normalize_hint). Otherwise, this function may fail or return a wrong result

Parameters

value – value to test
tp – type hint to check against. Must be normalized

Returns

True if the value is valid for the type hint, False otherwise

Raises

TypeHintError – the type hint could not be handled