Usage

Note

For extended and more in depth examples, refer to Examples

The following example illustrates how this module works.

from json2py.models import *
class Example(NestedField):
    hello = TextField(name = 'hi')
    integer = IntegerField()
    floating = FloatField()

class ExampleList(ListField):
    __model__ = Example

dict_var = {'hi': 'world', 'integer': 1000, 'floating': 10.5, 'ignored': "you won't see me"}
list_var = [dict_var] * 3

myMappedList = ExampleList(list_var)

myMappedList[1].integer.value = 1234

print myMappedList.json_encode(indent = 4)

Should return something like:

[
    {
        "integer": 1000,
        "floating": 10.5,
        "hi": "world"
    },
    {
        "integer": 1234,
        "floating": 10.5,
        "hi": "world"
    },
    {
        "integer": 1000,
        "floating": 10.5,
        "hi": "world"
    }
]

Models

Note

The classes of this modules are intended to be reimplemented in order to make use of this module.

Models represent basic JSON data types. The usage of this models is intended to be subclassed in order to fully map the original JSON structure.

BaseField

class json2py.models.BaseField(value=None, name=None, required=True)

Base Class holding and defining common features for all the other subclasses.

Parameters:

• value – Value to be stored
• name – Name of the field in source data.
• required – Whether raise LookupError when key is missing or not.

Note:

This class must be treated as abstract class and should not be reimplemented.

json_decode(data, **kwargs)

Parses a JSON-string into this object. This method is intended to build the JSON to Object map, so it doesn’t return any value, instead, the object is built into itself.

Parameters:

• data – JSON-string passed to json.loads()
• kwargs – Parameters passed to json.loads()

json_encode(**kwargs)

Converts an object of class BaseField into JSON representation (string) using BaseEncoder JSONEncoder.

Parameters:kwargs – Parameters passed to json.dumps() Returns:JSON-string representation of this object.

TextField

class json2py.models.TextField(value=None, name=None, required=True)

Class representing a string field in JSON.

Parameters:

• value – It is the raw data that is this object will represent once parsed.
• name – It has the same meaning as in BaseField
• required – It has the same meaning as in BaseField

Raises:

ParseException – If value is not a string nor None

IntegerField

class json2py.models.IntegerField(value=None, name=None, required=True)

Class representing an integer field in JSON.

Parameters:

• value – It is the raw data that is this object will represent once parsed.
• name – It has the same meaning as in BaseField
• required – It has the same meaning as in BaseField

Raises:

ParseException – If value is not a integer nor None

FloatField

class json2py.models.FloatField(value=None, name=None, required=True)

Class representing a float field in JSON.

Parameters:

• value – It is the raw data that is this object will represent once parsed.
• name – It has the same meaning as in BaseField
• required – It has the same meaning as in BaseField

Raises:

ParseException – If value is not a float nor None

BooleanField

class json2py.models.BooleanField(value=None, name=None, required=True)

Class representing boolean field in JSON.

Parameters:

• value – It is the raw data that is this object will represent once parsed.
• name – It has the same meaning as in BaseField
• required – It has the same meaning as in BaseField

Raises:

ParseException – If value is not boolean nor None

NestedField

class json2py.models.NestedField(value=None, name=None, required=True)

Class representing a document field in JSON.

Parameters:

• value – It is the raw data that is this object will represent once parsed.
• name – It has the same meaning as in BaseField
• required – It has the same meaning as in BaseField

Raises:

• ParseException – If value is not a dict nor None
• InvalidAttribute – If a reserved keyword is used as attribute

Note:

Reserved keywords are: name, value and required

Note:

For use cases and examples refer to Examples

ListField

class json2py.models.ListField(value=None, name=None, required=True)

Class representing a list field in JSON. This class implements list interface so you can slicing, appending, popping, etc.

Parameters:

• name – It has the same meaning as in BaseField
• value – It is the raw data that is this object will represent once parsed.
• required – It has the same meaning as in BaseField

Raises:

ParseException – If value is not a list nor None

Note:

Hinting the structure of values of the list should be done using the meta variable __model__ inside class reimplementation.

Note:

JSON lists’ values can be of any type even in the same list, but in real world apps, every JSON lists’ values should be of the same type, this behaviour also simplifies this module, so this class expects that all values in lists must have the same structure.

DateField

class json2py.models.DateField(value=None, name=None, required=True, formatting='%Y-%m-%dT%H:%M:%SZ')

Class used to parse and represent dates. It makes use of datetime and dateutil.

Parameters:

• name – It has the same meaning as in BaseField
• value – It is the raw data that is this object will represent once parsed.
• required – It has the same meaning as in BaseField
• formatting – Format used to represent date.

Raises:

ParseException – If value is not valid nor None

Note:

Several format’s can be in formatting: auto: use dateutil.parser.parse(), timestamp: provide UNIX timestamp and use datetime.datetime.utcfromtimestamp() and custom string: use any format in compliance with datetime.datetime.strptime() valid formats.