Reference Guide

This module contains functionality to serialize and deserialize objects.

JSON

en_serialization.json

This module provides classes and functions to make it easier to work with JSON.

class JsonArray(json_array)

This class wraps a JSON array into a similar interface to a list.

It also wraps the contents of the array into JsonObject or JsonArray where applies.

json_array = [
    1,
    'two',
    {
        'prop': 'value'
    }
]

arr = JsonArray(json_array)
arr[0]          # -> 1
arr[-3]         # -> 1
arr[1]          # -> 'two'
arr[-2]         # -> 'two'
arr[2].prop     # -> 'value'
arr[-1].prop    # -> 'value'
arr[3]          # -> raises IndexError
arr[-4]         # -> raises IndexError

class JsonObject(json_obj)

This class wraps a dictionary object and allows accessing values using the keys in the dictionary as attributes of the object.

This class handles attributes that contain other dictionaries (JSON object) and lists (JSON arrays) returning an appropriate wrapper. This makes it easier to handle nested objects and arrays inside the main dictionary.

If the attribute specified is not in the dictionary, it returns None, which makes this class suitable for PATCH payloads.

json_obj = {
    'title': 'The Lord of the Rings',
    'author': 'J.R.R. Tolkien,
    'stars': 5,
    'categories': ['fiction', 'fantasy', 'adventure'],
    'editions': [
        {
            'edition': 1,
            'year': 1952
        },
        {
            'edition': 2,
            'year': 1956
        }
    ],
    'reference': {
        'isbn': '12345678',
        'year': '2020'
    }

}

obj = JsonObject(json_obj)
obj.title               # -> 'The Lord of the Rings'
obj.title               # -> 'J.R.R. Tolkien'
obj.copyright           # -> None
obj.stars               # -> 5
obj.categories[1]       # -> 'fantasy'
obj.editions[0].year    # -> 1952

class Serializable

Default implementation of the Serializable interface. Sub-classes can can implement _add_data() to support the full interface.

import en_core.serialization.json as sj

class Person(sj.Serializable):
    def __init__(self, first_name, last_name):
        self.first_name = first_name
        self.last_name = last_name

    def _add_data(self, serialized):
        serialized.update(first_name=self.first_name, last_name=self.last_name)

person = Person('John', 'Smith')
person.to_dict()    # -> {'first_name': 'John','last_name': 'Smith'}
person.to_json()    # -> {'firstName': 'John','lastName': 'Smith'}

to_dict()

Serializes object using python case keys.

Returns: Dictionary representation of the object with python case keys.
Return type: dict

to_json()

Serializes object using camel case keys.

Returns: Dictionary representation of the object with camel case keys.
Return type: dict

class StrictJsonObject(json_obj)

This class wraps a dictionary object and allows accessing values using the keys in the dictionary as attributes of the object.

This class handles attributes that contain other dictionaries (JSON object) and lists (JSON arrays) returning an appropriate wrapper. This makes it easier to handle nested objects and arrays inside the main dictionary.

If the attribute specified is not in the dictionary, it raises an AttributeError exception.

json_obj = {
    'title': 'The Lord of the Rings',
    'author': 'J.R.R. Tolkien,
    'stars': 5,
    'categories': ['fiction', 'fantasy', 'adventure'],
    'editions': [
        {
            'edition': 1,
            'year': 1952
        },
        {
            'edition': 2,
            'year': 1956
        }
    ],
    'reference': {
        'isbn': '12345678',
        'year': '2020'
    }

}

obj = StrictJsonObject(json_obj)
obj.title               # -> 'The Lord of the Rings'
obj.title               # -> 'J.R.R. Tolkien'
obj.copyright           # -> raises AttributeError
obj.stars               # -> 5
obj.categories[1]       # -> 'fantasy'
obj.editions[0].year    # -> 1952

keys_to_camel_case(dictionary)

Converts all the keys in a dictionary to camel case going deep into values that are also dictionaries.

Parameters: dictionary (dict) – Dictionary object for which to convert all the keys to camel case.
Returns: The dictionary with all keys converted to camel case.
Return type: dict

keys_to_python_case(dictionary)

Converts all the keys in a dictionary to Python case going deep into values that are also dictionaries.

Parameters: dictionary (dict) – Dictionary object for which to convert all the keys to Python case.
Returns: The dictionary with all the keys converted to python case.
Return type: dict

The following example shows how it works:

from en_core.serialization.json import keys_to_python_case

to_camel_case(py_attribute)

Converts a python attribute name (snake case) to camel case.

Parameters: py_attribute (str) – String in snake case format to be converted.
Returns: The converted camel case string.
Return type: str

The following code example shows how this function works:

from en_core.serialization.json import to_camel_case

to_camel_case('simple')            # -> 'simple'
to_camel_case('snake_case')        # -> 'snakeCase'
to_camel_case('alreadyCamelCase')  # -> 'alreadyCamelCase'

to_python_case(camel_case)

Converts a camel case name to python attribute name (snake case).

Parameters: camel_case (str) – String in camel case format to be converted.
Returns: The converted snake case string.
Return type: str

The following code example shows how this function works:

from ptcore.serializers import to_python_case

to_python_case('simple')            # -> 'simple'
to_python_case('camelCase')         # -> 'camel_case'
to_python_case('already_python')    # -> 'already_python'