wysdom

A Python library for building custom document object models (DOMs) with built-in JSON schema checking.

Installation

In your system console, run:

pip install wysdom

Development Environment

To install a development environment with dependencies for docs and testing, clone this repo to your local system and run:

pip install -e .[dev]

Documentation

API documentation and examples can be found at:

https://wysdom.readthedocs.io

Motivation

A common requirement in Python projects is to be able to load serialized structured data into Python objects. Typically, you might begin by using dictionaries to store this data and a library like json or PyYAML to parse the input.

However, this simple approach may create additional work elsewhere in your project, for the following four reasons.

First, the serialized data you are loading might be user-generated, untrusted strings, and so some validation is necessary to check that the document schema matches what you are expecting.

Second, you may want to provide some promises to the rest of your application about the attributes that exist in your data object and what their data types are. For example, given a data object config which holds your application's configuration parameters, it is preferable to know that config.allow_nulls is a bool, as opposed to the subscript access style config['allow_nulls'] which may return a KeyError or an unexpected data type. This also enables your data objects to be covered by static type checking.

Third, you may want to add some additional functionality to your data objects in the form of properties and methods, including within the substructure of your data object. For example, a method config.database.test_connection().

Fourth, you may want to pass some sub-elements of your data object to components in your application, but have that sub-element retain awareness of the whole document. For example, a class instance db_service = DatabaseService(config.database) might need to access some attributes from the parent object config.

What wysdom does

With wysdom, you have one simple declarative way of defining the class structure of your data objects. You can then instantiate a data object using raw data in dict form, or directly deserialize it using one of wysdom's mixin classes.

Objects created by wysdom retain an awareness of the overall Document Object Model (DOM), which can be queried using the supplied functions document(obj), parent(obj) and key(obj).

Classes created by wysdom also auto-generate a JSON object schema and use the jsonschema library to enable you to validate potential input.

Example Usage

User class definition:

from wysdom import (
    UserObject, UserProperty, SchemaArray, SchemaDict, key
)

class Address(UserObject):
    first_line = UserProperty(str)
    second_line = UserProperty(str)
    city = UserProperty(str)
    postal_code = UserProperty(int)

class Vehicle(UserObject):
    color: str = UserProperty(str)
    description: str = UserProperty(str)

    @property
    def license(self):
        return key(self)

class Person(UserObject):
    first_name = UserProperty(str)
    last_name = UserProperty(str)
    current_address = UserProperty(Address)
    previous_addresses = UserProperty(SchemaArray(Address))
    vehicles = UserProperty(SchemaDict(Vehicle))

Loading from dict:

person_instance = Person({
  "first_name": "Marge",
  "last_name": "Simpson",
  "current_address": {
    "first_line": "123 Fake Street",
    "second_line": "",
    "city": "Springfield",
    "postal_code": 58008
  },
  "previous_addresses": [{
    "first_line": "742 Evergreen Terrace",
    "second_line": "",
    "city": "Springfield",
    "postal_code": 58008
  }],
  "vehicles": {
    "eabf04": {
      "color": "orange",
      "description": "Station Wagon"
    }
  }
})

Reading attributes:

>>> person_instance.last_name
'Simpson'

>>> person_instance.current_address.first_line
'123 Fake Street'

>>> person_instance.previous_addresses[0].first_line
'742 Evergreen Terrace'

>>> person_instance.vehicles["eabf04"].color
'orange'

>>> person_instance.vehicles["eabf04"].license
'eabf04'