Basic API specifications

Abstract classes for unified storage/query API with various backends.

Derivative classes are expected to be either complete implementations or wrappers for external libraries. The latter is assumed to be a better solution as PyModels is only one of the possible layers. It is always a good idea to provide different levels of abstraction and let others combine them as needed.

The backends do not have to subclass BaseStorage and BaseQuery. However, they must closely follow their API.

class pymodels.backends.base.BaseStorage(**kw)

clear()

Clears the whole storage from data, resets autoincrement counters.

delete(key)

Deletes record with given primary key.

get(model, primary_key)

Returns model instance for given model and primary key. Raises KeyError if there is no item with given key in the database.

get_query()

Returns a Query object bound to this storage.

save(model, data, primary_key=None)

Saves given model instance into the storage. Returns primary key.

Parameters:

• model – model class
• data – dict containing all properties to be saved
• primary_key – the key for given object; if undefined, will be generated

Note that you must provide current primary key for a model instance which is already in the database in order to update it instead of copying it.

class pymodels.backends.base.BaseQuery(storage, model)

count()

Returns the number of records that match given query. The result of q.count() is exactly equivalent to the result of len(q). The implementation details do not differ by default, but it is recommended that the backends stick to the following convention:

• __len__ executes the query, retrieves all matching records and tests the length of the resulting list;
• count executes a special query that only returns a single value: the number of matching records.

Thus, __len__ is more suitable when you are going to iterate the records anyway (and do no extra queries), while count is better when you just want to check if the records exist, or to only use a part of matching records (i.e. a slice).

delete()

Deletes all records that match current query.

order_by(name)

Returns a query object with same conditions but with results sorted by given column.

Parameters:

• name – string: name of the column by which results should be sorted. If the name begins with a -, results will come in reversed order.

values(name)

Returns a list of unique values for given column name.

where(**conditions)

Returns Query instance filtered by given conditions. The conditions are specified by backend’s underlying API.

where_not(**conditions)

Returns Query instance. Inverted version of where().