API¶
-
exception
jsontransform.
ConfigurationError
[source]¶ The passed
JSONObject
was not configured correctly.
-
exception
jsontransform.
ConstraintViolationError
[source]¶ A constraint which has been defined on a
field()
has been violated.
-
class
jsontransform.
FieldMode
[source]¶ The
FieldMode
describes the behavior of thefield()
during the encoding/decoding process. It marks that thefield()
should not be in the JSON document when theJSONObject
is encoded but it should be decoded and vice versa.
-
class
jsontransform.
JSONDecoder
[source]¶ This class offers methods to decode a JSON document into a
JSONObject
. AJSONObject
can be decoded from- an str
- a dict
- a write() supporting file-like object
-
from_json_dict
(json_dict, target=None)[source]¶ Decode a python dict into a
JSONObject
. The dict MUST be JSON conform so it cannot contain other object instances.Parameters: - json_dict – The dict which should be decoded
- target – (optional) The type of the target JSONObject into which this dict should be decoded. When this is empty then the target JSONObject will be searched automatically
Raises: - ConfigurationError – When the target JSONObject does NOT define any JSON fields
- TypeError – When the signature of the passed target did NOT match the signature of the passed dict i.e. they had no fields in common
- MissingObjectError – When no target JSONObject was specified AND no matching JSONObject could be found
- ConstraintViolationError – When a field inside the dict violated a constraint which is defined on the target JSONObject e.g. a required field is missing
Returns: A JSONObject which matched the signature of the dict and with the values of it
-
from_json_file
(json_file, target=None)[source]¶ Decode a read() supporting file-like object into a
JSONObject
. The file-like object MUST contain a valid JSON document.Parameters: - json_file – The read() supporting file-like object which should be decoded into a JSONObject
- target – (optional) The type of the target JSONObject into which this file-like object should be decoded. When this is empty then the target JSONObject will be searched automatically
Raises: - ConfigurationError – When the target JSONObject does NOT define any JSON fields
- TypeError – When the signature of the passed target did NOT match the signature of the JSON document which was read from the passed file-like object i.e. they had no fields in common
- MissingObjectError – When no target JSONObject was specified AND no matching JSONObject could be found
- ConstraintViolationError – When a field of the JSON document which was read from the file-like object violated a constraint which is defined on the target JSONObject e.g. a required field is missing
Returns: A JSONObject which matched the signature of the JSON document which the read() supporting file-like object returned and with the values of it
-
from_json_str
(json_str, target=None)[source]¶ Decode an str into a
JSONObject
. The str MUST contain a JSON document.Parameters: - json_str – The str which should be decoded
- target – (optional) The type of the target JSONObject into which this str should be decoded. When this is empty then the target JSONObject will be searched automatically
Raises: - ConfigurationError – When the target JSONObject does NOT define any JSON fields
- TypeError – When the signature of the passed target did NOT match the signature of the JSON document which was inside the passed str i.e. they had no fields in common
- MissingObjectError – When no target JSONObject was specified AND no matching JSONObject could be found
- ConstraintViolationError – When a field of the JSON document which was inside the str violated a constraint which is defined on the target JSONObject e.g. a required field is missing
Returns: A JSONObject which matched the signature of the JSON document from the str and with the values of it
-
static
validate_required_fields
(json_object, json_dict)[source]¶ Validate if a dict which will be decoded satisfied all required fields of the
JSONObject
into which it will be decoded.Parameters: - json_object – The instance of the JSONObject into which the dict will be decoded
- json_dict – The dict which should be validated
Raises: ConstraintValidationError – When a required field is missing
-
class
jsontransform.
JSONEncoder
[source]¶ This class offers methods to encode a
JSONObject
into JSON document. AJSONObject
can be encoded to- an str
- a dict
- a write() supporting file-like object
-
to_json_dict
(json_object)[source]¶ Encode an instance of a
JSONObject
into a python dict.Parameters: json_object – The instance of the JSONObject which should be encoded
Raises: - ConfigurationError – When the JSONObject of which an instance was passed does NOT define any JSON fields
- TypeError – When the type of a field in the JSONObject is not encodable
Returns: A dict which represents the passed JSONObject and is JSON conform
-
to_json_file
(json_object, json_file)[source]¶ Encode an instance of a
JSONObject
and write the result into a write() supporting file-like object.Parameters: - json_object – The instance of the JSONObject which should be encoded
- json_file – A write() supporting file-like object
Raises: - ConfigurationError – When the JSONObject of which an instance was passed does NOT define any JSON fields
- TypeError – When the type of a field in the JSONObject is not encodable
-
to_json_str
(json_object)[source]¶ Encode an instance of a
JSONObject
into an str which contains a JSON document.Parameters: json_object – The instance of the JSONObject which should be encoded
Raises: - ConfigurationError – When the JSONObject of which an instance was passed does NOT define any JSON fields
- TypeError – When the type of a field in the JSONObject is not encodable
Returns: An str which contains the JSON representation of the passed JSONObject
-
class
jsontransform.
JSONObject
[source]¶ Every entity/class which is intended to be encodable and decodable to a JSON document MUST inherit/extend this class.
-
exception
jsontransform.
MissingObjectError
[source]¶ No
JSONObject
which matches the signature of the passed JSON document could be found.
-
jsontransform.
dump
(json_object, json_file)[source]¶ Shortcut for instantiating a new
JSONEncoder
and calling theto_json_file()
function.See also
For more information you can look at the doc of
JSONEncoder.to_json_file()
.
-
jsontransform.
dumpd
(json_object)[source]¶ Shortcut for instantiating a new
JSONEncoder
and calling theto_json_dict()
function.See also
For more information you can look at the doc of
JSONEncoder.to_json_dict()
.
-
jsontransform.
dumps
(json_object)[source]¶ Shortcut for instantiating a new
JSONEncoder
and calling theto_json_str()
function.See also
For more information you can look at the doc of
JSONEncoder.to_json_str()
.
-
jsontransform.
field
(field_name=None, required=False, mode='ed', func=None)[source]¶ The
field()
decorator is used to mark that aproperty
inside aJSONObject
is a JSON field so it will appear in the JSON document when theJSONObject
is encoded or decoded.Note
- The brackets () after the @field decorator are important even when no additional arguments are given
- The
property
decorator must be at the top or else the function won’t be recognized as a property
Parameters: - func – The method which is decorated with @property decorator.
- field_name – (optional) A name/alias for the field (how it should appear in the JSON document) since by default the name of the property will be used.
- required – (optional) A bool which indicates if this field is mandatory for the decoding process. When a field which is marked as required does NOT exist in the JSON document from which the JSONObject is decoded from, a ConstraintViolationError will be raised. (False by default)
- mode – (optional) The FieldMode of the field. (ENCODE_DECODE by default)
-
jsontransform.
load
(json_file, target=None)[source]¶ Shortcut for instantiating a new
JSONDecoder
and calling thefrom_json_file()
function.See also
For more information you can look at the doc of
JSONDecoder.from_json_file()
.
-
jsontransform.
loadd
(json_dict, target=None)[source]¶ Shortcut for instantiating a new
JSONDecoder
and calling thefrom_json_dict()
function.See also
For more information you can look at the doc of
JSONDecoder.from_json_dict()
.
-
jsontransform.
loads
(json_str, target=None)[source]¶ Shortcut for instantiating a new
JSONDecoder
and calling thefrom_json_str()
function.See also
For more information you can look at the doc of
JSONDecoder.from_json_str()
.