Add typing support to python JSON serialization.
Project description
typing-json
Add typing support to python JSON serialization.
typechecking
The typechecking module contains utilities for dynamic typechecking which support relevant types from the typing and typing_extensions libraries.
is_hashable
def is_hashable(t: Any, failure_callback: Optional[Callable[[str], None]] = None) -> bool:
...
The function is_hashable(t)
returns True
if and only if the t
argument is one of the types considered to be hashable for the purposes of dynamic typechecking in this package. Types currently deemed to be hashable by this function:
- the standard types
bool
,int
,float
,complex
,str
,bytes
,range
,slice
,type
andNoneType
(as well as the valueNone
, treated equivalently toNoneType
); - the
typing
typesTuple[_T1,...]
(single-type variadic tuple),Tuple[_T1,...,_TN]
(multi-type fixed arity tuple),FrozenSet[_T]
,Optional[_T]
,Union[_T1,...,_TN]
where_T
,_S
,_T1
, ...,_TN
are themselves hashable types; - the
typing_extensions
typeLiteral[_v1, ..., _vn]
where_v1
, ...,_vn
are of hashable standard type (see above); - types created using
typing.NamedTuple
using hashable field types;
Support for enum types and NewType is planned (see pull request #5).
If present, failure_callback
is called to log all reasons why t
fails to be hashable, in the order in which they arise.
is_typecheckable
def is_typecheckable(t: Any, failure_callback: Optional[Callable[[str], None]] = None) -> bool:
...
The function is_typecheckable(t)
returns True
if and only if the t
argument is one of the types supported for dynamic typechecking using the is_instance(obj, t)
function from the same module. Currently supported types:
- the standard types
bool
,int
,float
,complex
,str
,bytes
,bytearray
,memoryview
,list
,tuple
,range
,slice
,set
,frozenset
,dict
,type
,NoneType
andobject
(as well as the valueNone
, treated equivalently toNoneType
); - the
collections
typesdeque
andOrderedDict
; - the
typing
typesAny
,List[_T]
,Tuple[_T1,...]
(single-type variadic tuple),Tuple[_T1,...,_TN]
(multi-type fixed arity tuple),Set[_T]
,FrozenSet[_T]
,Dict[_T, _S]
,OrderedDict[_T, _S]
,Mapping[_T, _S]
,Deque[_T]
,Optional[_T]
,Union[_T1,...,_TN]
where_T
,_S
,_T1
, ...,_TN
are themselves supported types; - the
typing_extensions
typeLiteral[_v1, ..., _vn]
where_v1
, ...,_vn
are of typecheckable standard ofcollections
type (see above); - types created using
typing.NamedTuple
using typecheckable field types;
Arbitrary classes are currently not supported, regardless of type annotations. Support for types created using collections.namedtuple
is not planned. Support for enum types and NewType is planned (see pull request #5).
If present, failure_callback
is called to log all reasons why t
fails to be typecheckable, in the order in which they arise.
is_instance
def is_instance(obj: Any, t: Any, failure_callback: Optional[Callable[[str], None]] = None) -> bool:
...
The function is_instance(obj, t)
returns True
if and only if the obj
argument is of type t
. If t
is not typecheckable according to is_typecheckable(t)
then TypeError
is raised.
If present, failure_callback
is called to log all reasons why obj
fails to be an instance of t
, in the order in which they arise.
is_namedtuple
def is_namedtuple(t: Any) -> bool:
...
The function is_namedtuple(t)
returns True
if the obj
argument was created using typing.NamedTuple
and all field types are typecheckable. It is currently possible to fool this method by using collections.namedtuple
and manually adding a _field_types:
dictionary with string keys and typecheckable types.
If present, failure_callback
is called to log all reasons why t
fails to be a NamedTuple, in the order in which they arise.
encoding
is_json_encodable
def is_json_encodable(t: Any, failure_callback: Optional[Callable[[str], None]] = None) -> bool:
...
The function is_json_encodable(t)
returns True
if and only if t
is a json-encodable type according to this package. At present, the following are json-encodable types:
- the standard types
bool
,int
,float
,str
, andNoneType
(as well as the valueNone
, treated equivalently toNoneType
); - any
t
such thatis_namedtuple(t)
and such that all field types are json-encodable themselves; - the
typing
typesList[_T]
,Set[_T]
,FrozenSet[_T]
,Deque[_T]
,Tuple[_T,...]
,Tuple[_T1,...,_TN]
,Dict[str, _T]
,OrderedDict[str, _T]
,Mapping[str, _T]
,Union[_T1,...,_TN]
,Optional[_T]
where_T
,_T1
, ...,_TN
are themselves json-encodable types; - the
typing_extensions
typeLiteral[_v1,...,_vn]
, where where each_vj in [_v1,...,_vn]
is of typebool
,int
,float
,str
orNoneType
.
Future support is planned for more typing
and typing_extensions
types, including enum types and NewType (see pull request #5).
If present, failure_callback
is called to log all reasons why t
fails to be json-encodable, in the order in which they arise.
to_json_obj
def to_json_obj(obj: Any, t: Any) -> Any:
...
The function to_json_obj(obj, t)
takes an object obj
and a json encodable type t
and converts obj
into a natively--json-compatible object with the same fields and types. The conversion goes as follows:
- if
t in (bool, int, float, str)
,obj
is returned unaltered; - if
t in (None, NoneType, ...)
,None
is returned; - if
is_namedtuple(t)
, acollections.OrderedDict
is returned with the fields of the named tuple as keys and respective values recursively converted to natively--json-compatible; - if
t
isUnion[_T1,...,_TN]
,obj
is converted to natively--json-compatible type according to the first type_Tj
in the sequence_T1
,...,_TN
such thatis_instance(obj, _Tj)
; - the type
Optional[_T]
is treated asUnion[_T, NoneType]
; - if
t
isLiteral[_v1,...,_vN]
,obj
is returned unaltered; - if
t
is one ofList[_T]
,Set[_T]
,FrozenSet[_T]
,Deque[_T]
,Tuple[_T,...]
a list is returned, containing all elements ofobj
recursively converted to natively--json-compatible objects using type_T
for the conversion; - if
t
isTuple[_T1,...,_TN]
, a list is returned, containing all elements ofobj
recursively converted to natively--json-compatible objects using types_T1
,...,_TN
for the conversion of the elementsx1
,...,xN
ofobj
; - if
t
isDict[_S, _T]
orMapping[_S, _T]
, a dictionary is returned with keys and values recursively converted to natively--json-compatible type according to types_S
and_T
respectively, and the string version of the keys json is used if they are not one ofbool
,int
,float
,str
orNoneType
; - if
t
isOrderedDict[_S, _T]
, an dictionary is returned with keys and values recursively converted to natively--json-compatible type according to types_S
and_T
respectively, and the string version of the keys json is used if they are not one ofbool
,int
,float
,str
orNoneType
;
If t
is not json-encodable according to is_json_encodable(t)
then TypeError
is raised. If obj
is not of type t
according to is_instance(obj, t)
then TypeError
is raised.
For the purposes of this library, natively--json-compatible types are: bool
, int
, float
, str
, NoneType
, list
, dict
and collections.OrderedDict
.
dump and dumps
def dump(obj: Any, encoded_type: Any, ...):
...
def dumps(obj: Any, encoded_type: Any, ...):
...
The functions dump
and dumps
of typing_json
mimic the functions dump
and dumps
of the standard json
library, first performing a conversion of obj
from json-encodable type encoded_type
to a json object before dumping.
decoding
from_json_obj
def from_json_obj(obj: Any, t: Any) -> Any:
...
The function to_json_obj(obj, t)
takes an object obj
and a json encodable type t
and converts obj
into an equivalent object of type t
. The conversion goes as follows:
- if
t in (bool, int, float, str)
,obj
is returned unaltered (TypeError
is raised ifnot isinstance(obj, t)
); - if
t in (None, NoneType)
,None
is returned (TypeError
is raised ifobj is not None
); - if
t is ...
,...
is returned (TypeError
is raised ifobj is not None
); - if
is_namedtuple(t)
, the key values of the (ordered) dictionaryobj
are recursively converted to the types of the fields oft
with the same keys and any missing key is replaced with it default value int
, if present (TypeError
is raised ifobj
is not a (ordered) dictionary, ifobj
contains keys which are not fields oft
, or if a non-default field oft
does not appear as a key inobj
); - if
t
isUnion[_T1,..._TN]
then conversion ofobj
to each type_Tj
listed in the union is attempted in order and the first successful result is returned (TypeError
is raised if no conversion is successful); - if
t
isLiteral
thenobj
is returned unaltered (TypeError
is raised ifnot is_instance(obj, t)
); - if
t
isList[_T]
then all members ofobj
are recursively converted to type_T
and a list of the results is returned (TypeError
is raised ifobj
is not a list); - if
t
isDeque[_T]
then all members ofobj
are recursively converted to type_T
and a deque of the results is returned (TypeError
is raised ifobj
is not a list); - if
t
isSet[_T]
then all members ofobj
are recursively converted to type_T
and a set of the results is returned (TypeError
is raised ifobj
is not a list, order preservation is not guaranteed); - if
t
isFrozenSet[_T]
then all members ofobj
are recursively converted to type_T
and a frozenset of the results is returned (TypeError
is raised ifobj
is not a list, order preservation is not guaranteed); - if
t
isTuple[_T,...]
then all members ofobj
are recursively converted to type_T
and a tuple of the results is returned (TypeError
is raised ifobj
is not a list); - if
t
isTuple[_TN,...,_TN]
then all members ofobj
are recursively converted to the respective types_Tj
and a tuple of the results is returned (TypeError
is raised ifobj
is not a list or if the length does not match the required length for the tuple); - if
t
isDict[_S, _T]
orMapping[_S, _T]
then all keys and values ofobj
are recursively converted to types_S
and_T
respectively (if_S
is not one ofbool
,int
,float
,str
,NoneType
orNone
, the keys are first json-parsed from strings), and a dict of the results is returned (TypeError
is raised ifobj
is not a (ordered) dictionary); - if
t
isOrderedDict[_S, _T]
then all keys and values ofobj
are recursively converted to types_S
and_T
respectively (if_S
is not one ofbool
,int
,float
,str
,NoneType
orNone
, the keys are first json-parsed from strings), and an ordered dict of the results is returned (TypeError
is raised ifobj
is not an ordered dictionary);
If t
is not json-encodable according to is_json_encodable(t)
then TypeError
is raised.
load and loads
def load(fp, decoded_type: Any, ...) -> Any:
...
def dumps(s: str, decoded_type: Any, ...) -> Any:
...
The functions load
and loads
of typing_json
mimic the functions load
and loads
of the standard json
library, performing a conversion of the loaded json object to json-encodable type decoded_type
before returning.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for typing_json-0.0.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 15d683be4be67a71f328b27285b0b1dd636ca92839e3ba87ce9726b273334750 |
|
MD5 | c1e1e45a8ba8907e25c7a5b71b9874fe |
|
BLAKE2b-256 | de3eb76dbd2ff1bf7af37574779cf955b9a85345c7b8cfcb8b00c70090cb7d34 |