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 the field() during the encoding/decoding process. It marks that the field() should not be in the JSON document when the JSONObject is encoded but it should be decoded and vice versa.

DECODE = 'd'

Indicates that the field() can ONLY be decoded.

ENCODE = 'e'

Indicates that the field() can ONLY be encoded.

ENCODE_DECODE = 'ed'

Indicates that the field() can be encoded AND decoded.

class jsontransform.JSONDecoder[source]

This class offers methods to decode a JSON document into a JSONObject. A JSONObject 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. A JSONObject 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 the to_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 the to_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 the to_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 a property inside a JSONObject is a JSON field so it will appear in the JSON document when the JSONObject 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 the from_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 the from_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 the from_json_str() function.

See also

For more information you can look at the doc of JSONDecoder.from_json_str().