Wiki
Clone wikijson-transform / API Design
API Design
JSONObject class
Every entity/class which is intended to be encodable and decodable to a JSON document MUST inherit/extend this class
field decorator
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
Parameters
- field_name (optional) - A name/alias for the
field
(how it should appear in the JSON document) since by default the name of theproperty
will be used - required (optional) - A
bool
which indicates if thisfield
is mandatory for the decoding process. When afield
which is marked as required does NOT exist in the JSON document from which theJSONObject
is decoded from, aConstraintViolationError
will be raised (False by default) - mode (optional) - The
FieldMode
of thefield
(ENCODE_DECODE by default)
FieldMode class
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
Constants
- ENCODE - Indicates that the field can ONLY be encoded
- DECODE - Indicates that the field can ONLY be decoded
- ENCODE_DECODE - Indicates that the field can be encoded AND decoded
JSONEncoder class
This class offers methods to encode a JSONObject
into a JSON document. A JSONObject
can be encoded to
- an
str
- a
dict
- a
write()
supporting file-like object
Methods
to_json_dict
Encode an instance of a JSONObject
into a python dict
Parameters
- json_object - The instance of the
JSONObject
which should be encoded
Exceptions
- ConfigurationError When the
JSONObject
of which an instance was passed does NOT define any JSON fields - TypeError When the type of a
field
in theJSONObject
is not encodable
Returns
A dict
which represents the passed JSONObject
and is JSON conform
to_json_str
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
Exceptions
- ConfigurationError When the
JSONObject
of which an instance was passed does NOT define any JSON fields - TypeError When the type of a
field
in theJSONObject
is not encodable
Returns
An str
which contains the JSON representation of the passed JSONObject
to_json_file
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 - f - A
write()
supporting file-like object
Exceptions
- ConfigurationError When the
JSONObject
of which an instance was passed does NOT define any JSON fields - TypeError When the type of a
field
in theJSONObject
is not encodable
JSONDecoder class
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
Methods
from_json_dict
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 thisdict
should be decoded. When this is empty then the targetJSONObject
will be searched automatically
Exceptions
- 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 matchingJSONObject
could be found - ConstraintViolationError When a field inside the
dict
violated a constraint which is defined on the targetJSONObject
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_str
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 thisstr
should be decoded. When this is empty then the targetJSONObject
will be searched automatically
Exceptions
- 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 matchingJSONObject
could be found - ConstraintViolationError When a field of the JSON document which was inside the
str
violated a constraint which is defined on the targetJSONObject
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
from_json_file
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 aJSONObject
- target (optional) - The type of the target
JSONObject
into which this file-like object should be decoded. When this is empty then the targetJSONObject
will be searched automatically
Exceptions
- 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 matchingJSONObject
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
dump function
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 - f - A
write()
supporting file-like object
Exceptions
- ConfigurationError When the
JSONObject
of which an instance was passed does NOT define any JSON fields - TypeError When the type of a
field
in theJSONObject
is not encodable
dumps function
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
Exceptions
- ConfigurationError When the
JSONObject
of which an instance was passed does NOT define any JSON fields - TypeError When the type of a
field
in theJSONObject
is not encodable
Returns
An str
which contains the JSON representation of the passed JSONObject
dumpd function
Encode an instance of a JSONObject
into a python dict
Parameters
- json_object - The instance of the
JSONObject
which should be encoded
Exceptions
- ConfigurationError When the
JSONObject
of which an instance was passed does NOT define any JSON fields - TypeError When the type of a
field
in theJSONObject
is not encodable
Returns
A dict
which represents the passed JSONObject
and is JSON conform
load function
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 aJSONObject
- target (optional) - The type of the target
JSONObject
into which this file-like object should be decoded. When this is empty then the targetJSONObject
will be searched automatically
Exceptions
- 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 matchingJSONObject
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
loads function
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 thisstr
should be decoded. When this is empty then the targetJSONObject
will be searched automatically
Exceptions
- 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 matchingJSONObject
could be found - ConstraintViolationError When a field of the JSON document which was inside the
str
violated a constraint which is defined on the targetJSONObject
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
loadd function
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 thisdict
should be decoded. When this is empty then the targetJSONObject
will be searched automatically
Exceptions
- 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 matchingJSONObject
could be found - ConstraintViolationError When a field inside the
dict
violated a constraint which is defined on the targetJSONObject
e.g. a required field is missing
Returns
A JSONObject
which matched the signature of the dict
and with the values of it
ConfigurationError Exception
The passed JSONObject
was not configured correctly
ConstraintViolationError Exception
A constraint which has been defined on a field
has been violated
MissingObjectError Exception
No JSONObject
which matches the signature of the passed JSON document could be found
Updated