Skip to content
This repository was archived by the owner on Jul 3, 2021. It is now read-only.

API Design

Jump to bottom
Peter edited this page Sep 20, 2018 · 1 revision

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 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)

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 the JSONObject 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 the JSONObject 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 the JSONObject 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 this dict should be decoded. When this is empty then the target JSONObject 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 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_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 this str should be decoded. When this is empty then the target JSONObject 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 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

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 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
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 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

dump function

Shortcut for instantiating a JSONEncoder and calling the to_json_file function.

dumps function

Shortcut for instantiating a JSONEncoder and calling the to_json_str function.

dumpd function

Shortcut for instantiating a JSONEncoder and calling the to_json_dict function.

load function

Shortcut for instantiating a JSONDecoder and calling the from_json_file function.

loads function

Shortcut for instantiating a JSONDecoder and calling the from_json_str function.

loadd function

Shortcut for instantiating a JSONDecoder and calling the from_json_dict function.

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

Clone this wiki locally