Add typing support to python JSON serialization.
Project description
typing-json
Add typing support to python JSON serialization.
typechecking module
The typechecking module contains utilities for dynamic typechecking which support relevant types from the typing and typing_extensions libraries.
is_typecheckable
def is_typecheckable(t: Any) -> 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
,Ellipsis
,NotImplemented
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]
,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 immutable (comparison is performed usingobj is _vj
, notobj == _vj
); - types created using
typing.NamedTuple
using typecheckable field types; Arbitrary classes are currently not supported, regardless of type annotations. Support for types created usingcollections.namedtuple
is not planned.
is_instance
def is_instance(obj: Any, t: Any) -> 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.
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.
encoding module
is_json_encodable
def is_json_encodable(t: Any) -> 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
,NoneType
andEllipsis
(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]
,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.
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[str, _T]
, a dictionary is returned containing the keys ofobj
as its keys and with the respective values recursively converted to natively--json-compatible type according to type_T
; - if
t
isOrderedDict[str, _T]
, an ordered dictionary is returned containing the keys ofobj
as its keys and with the respective values recursively converted to natively--json-compatible type according to type_T
;
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
.
decoding module
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[str, _T]
then all values ofobj
are recursively converted to type_T
and a dict of the results (with the same keys ofobj
) is returned (TypeError
is raised ifobj
is not a (ordered) dictionary or if any of its keys is not a string); - if
t
isOrderedDict[str, _T]
then all values ofobj
are recursively converted to type_T
and a ordered dict of the results (with the same keys ofobj
) is returned (TypeError
is raised ifobj
is not a ordered dictionary or if any of its keys is not a string);
If t
is not json-encodable according to is_json_encodable(t)
then TypeError
is raised.
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.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 40a1d9bd0ccbf956b7f6e4606b456d29cfd869829c1e440cfc13ad2249a0b973 |
|
MD5 | f5969a71a17c5021d599938866048f51 |
|
BLAKE2b-256 | 3014c972d69fe1f2c30f43cb0d88ee9841766e73848f42fe4cac4b9a48460e3a |