Welcome to Cinder Data’s documentation!¶

A library inspired by ember-data for python projects.

User Documentation¶

About¶

Cinder Data is a library inspired by ember-data for ember.js. It tries to abstract away all the complexities of dealing with REST and JSON api’s and giving you an orm style interface for creating, reading, updating and deleting models.

Warning

Cinder Data is in very early development and is not ready for production yet.

Right now cinder-data only supports a JSON API, it is specfically designed to work with Django, with the Django Rest Framework and the JSON api plugin installed.

pip install Django djangorestframework djangorestframework-jsonapi

Given time it will support adapters like ember-data allowing you to work with your own API’s.

Installing¶

From pip¶

pip install cinder-data

From source¶

git clone https://github.com/almcc/cinder-data.git
cd cinder-data
python setup.py install

Quick example¶

from cinder_data.model import DjangoModel
from cinder_data.store import Store
from schematics.types import StringType

class Car(DjangoModel):
    name = StringType()

store = Store('http://server:8000')

# GET http://server:8000/cars/1
record = store.find_record(Car, 1)

# GET http://server:8000/cars
first_page = store.find_all(Car)

# GET http://server:8000/cars?page=2
second_page = store.find_all(Car, params={'page': 2})

Developer Documentation¶

Your environment¶

The cinder-data development environment relies a lot on docker, so there are relativily few requirements for your development enviroment, namely docker, docker-compose and python-fabric. Everything else is handled by docker.

To get started just do the following:

git clone https://github.com/almcc/cinder-data.git
cd cinder-data
fab --list

You will get a list of the available helper commands.

Tip

If your unfortunate enought to suffer from #slowinternet run fab prep_docker and go make yourself a cup of tea. It will download and build all the docker containers you will need.

Testing¶

There are unit tests, run with fab run_unit_tests and there is some robot tests that loads up an example server application and tests using cinder-data to communicate with it. These are run with fab run_robot_tests

Building¶

travis-ci.org builds cinder-data, if there is a tag (should be in the form v<major>.<minor>.<fix>) it will also publish a pip package to pypi.

cinder_data¶

cinder_data package¶

Submodules¶

cinder_data.cache module¶

class cinder_data.cache.Cache¶

Bases: object

Cache interface

get_record(name, record_id)¶

Should retrieve a record with a given type name and record id.

Parameters:	name (string) – The name which the record is stored under. record_id (int) – The id of the record requested.
Raises:	`NotImplementedError`
Returns:	Should return the cached model.
Return type:	`cinder_data.model.CinderModel`

get_records(name)¶

Should get all the records in the cache under a given name.

Parameters:	name (string) – The name which the records are stored under.
Raises:	`NotImplementedError`
Returns:	Should return a list of `cinder_data.model.CinderModel` models.
Return type:	list

set_record(name, record_id, record)¶

Should save the record to the cache.

Parameters:	name (string) – The name which to store the record under. record_id (int) – The id of the record. record (`cinder_data.model.CinderModel`) – The model
Raises:	`NotImplementedError` – Description

class cinder_data.cache.MemoryCache¶

Bases: cinder_data.cache.Cache

A cache which uses in-process memmory.

Initialise the cache.

get_record(name, record_id)¶

Retrieve a record with a given type name and record id.

Parameters:	name (string) – The name which the record is stored under. record_id (int) – The id of the record requested.
Returns:	The cached model.
Return type:	`cinder_data.model.CinderModel`

get_records(name)¶

Returns all the records for the given name in the cache.

Parameters:	name (string) – The name which the required models are stored under.
Returns:	A list of `cinder_data.model.CinderModel` models.
Return type:	list

set_record(name, record_id, record)¶

Save a record into the cache.

Parameters:	name (string) – The name to save the model under. record_id (int) – The record id. record (`cinder_data.model.CinderModel`) – The model

cinder_data.model module¶

class cinder_data.model.CinderModel(raw_data=None, trusted_data=None, deserialize_mapping=None, init=True, partial=True, strict=True, validate=False, app_data=None, **kwargs)¶

Bases: schematics.models.Model

A basic model that assumes the model has an id attribute.

Note

cinder-data makes use of schematics for it’s models. Full documentation on Schematics can be found at: https://schematics.readthedocs.io/en/latest/

id¶: schematics.types.base.IntType – The model id.

id = <IntType() instance on CinderModel as 'id'>

class cinder_data.model.DjangoModel(raw_data=None, trusted_data=None, deserialize_mapping=None, init=True, partial=True, strict=True, validate=False, app_data=None, **kwargs)¶

Bases: cinder_data.model.CinderModel

A subclass of cinder_data.model.CinderModel the includes user Django Admin attributes.

created_at¶: schematics.types.base.DateTimeType – Django admin created_at

updated_at¶: schematics.types.base.DateTimeType – Django admin updated_at

created_at = <DateTimeType() instance on DjangoModel as 'created_at'>

id = <IntType() instance on DjangoModel as 'id'>¶

updated_at = <DateTimeType() instance on DjangoModel as 'updated_at'>

cinder_data.store module¶

class cinder_data.store.Store(host, namespace='', cache=None)¶

Bases: object

A central store for all CRUD like activilty for models.

Initialise the store.

Parameters:	host (string) – The host of your api, e.g. http://localhost:8000 namespace (string, optional) – An aditional name space to append to the host, e.g. api/v1 cache (`cinder_data.cache.Cache`, optional) – An instance of your chosen caching system that must be must adhear to the `cinder_data.cache.Cache` interface.

find_all(model_class, params={})¶

Returns an list of models from the API and caches the result.

Parameters:	model_class (`cinder_data.model.CinderModel`) – A subclass of `cinder_data.model.CinderModel` of your chosen model. params (dict, optional) – Description
Returns:	A list of instances of you model_class or and empty list.
Return type:	list

find_record(model_class, record_id, reload=False)¶

Returns a instance of model_class from the API or the local cache.

Parameters:	model_class (`cinder_data.model.CinderModel`) – A subclass of `cinder_data.model.CinderModel` of your chosen model. record_id (int) – The id of the record requested. reload (bool, optional) – Don’t return the cached version if reload==True.
Returns:	An instance of model_class or None.
Return type:	`cinder_data.model.CinderModel`

peek_all(model_class)¶

Returns a list of models from the local cache.

Parameters:	model_class (`cinder_data.model.CinderModel`) – A subclass of `cinder_data.model.CinderModel` of your chosen model.
Returns:	A list of instances of you model_class or and empty list.
Return type:	list

peek_record(model_class, record_id)¶

Returns an instance of the model_class from the cache if it is present.

Parameters:	model_class (`cinder_data.model.CinderModel`) – A subclass of `cinder_data.model.CinderModel` of your chosen model. record_id (int) – The id of the record requested.
Returns:	An instance of model_class or None.
Return type:	`cinder_data.model.CinderModel`