sondra.collection package

Submodules

• sondra.collection.signals module

Module contents

class sondra.collection.Collection(application)

Bases: collections.abc.MutableMapping

The collection is the workhorse of Sondra.

Collections are mutable mapping types, like dicts, whose keys are the keys in the database collection. The database table, or collection, has the same name as the collection’s slug with hyphens replaced by underscores for compatibility.

Collections expand on a document schema, specifying:

• properties that should be treated specially.
• the primary key
• indexes that should be built
• relationships to other collections

Like applications, collections have webservice endpoints:

http://localhost:5000/application/collection;(schema|help|json|geojson)
http://localhost:5000/application/collection.method;(schema|help|json)

These endpoints allow the user to create, update, filter, list, and delete objects in the collection, which are individual documents. Also, any methods that are exposed by the sondra.decorators.expose decorator are exposed as method endpoints.

To use Python to retrieve individual Document instances, starting with the suite:

> suite['app-name']['collection-name']['primary-key']
...
<sondra.document.Document object at 0x....>

The specials attribute is a dictionary of property names to sondra.document.ValueHandler instances, which tell the collection how to handle properties containing objects that aren’t standard JSON. This includes date-time objects and geometry, which is handled via the Shapely library. Shapely is not supported by readthedocs, so you must install it separately. See the individual ValueHandler subclasses in sondra.document for more information.

name

str – read-only. The name of the collection, based on the classname.

slug

str – read-only. The hyphen separated name of the collection, based on the classname

schema

str – read-only. The collection’s schema, based on the document_class

suite

sondra.suite.Suite – read-only. The suite this collection’s application is a part of. None for abstract classes.

application

sondra.application.Application – classes.

document_class

sondra.document.Document – The document class this collection contains. The schema is derived from this.

primary_key

str – The field (if different from id) to use as the primary key. Individual documents are referenced by primary key, both in the Python interface and the webservice interface.

private

bool=False – can be very useful for collections whose data should never be available over the ‘net.

specials

dict – A dictionary of properties to be treated specially.

indexes

[str]

relations

dict

anonymous_reads

bool=True

abstract

bool

table

ReQL

url

str

schema_url

str

__contains__(item)

Checks to see if the primary key is in the database.

Parameters:item (dict, Document, str, or int) – If a dict or a document, then the primary key will be checked. Str or ints are assumed to be the primary key. Returns:True or False.

__delitem__(key)

Delete an object from the database.

Sends pre- and post- delete signals. See signals documentation for more details.

Parameters:key (str or int) – The primary key for the document.

__getitem__(key)

Get an object from the database and populate an instance of self.document_class with its contents.

Parameters:key (str or int) – Primary key for the document. Returns:An instance of self.document_class with data from the database. Return type:Document Raises:KeyError if the object is not found in the database.

__setitem__(key, value)

Add or replace a document object to the database.

Sends pre- and post- save signals. See signals documentation for more details.

Parameters:

• key (str or int) – The primary key for the document.
• value – (dict or Document): If a Document, it should be this collection’s document_class.

abstract = True

anonymous_reads = True

application = None

create(value)

Create a document from a dict. Saves document before returning, and thus also sends pre- and post- save signals.

Parameters:value (dict) – The value to use for the new document. Returns:Document instance, guaranteed to have been saved.

create_table(*args, **kwargs)

Create the database table for this collection. Args and keyword args are sent along to the rethinkdb table_create function. Sends pre_table_creation and post_table_creation signals.

definitions = {}

delete(docs=None, **kwargs)

Delete a document or list of documents from the database.

Parameters:

• docs (Document or [Document] or [primary_key]) – List of documents to delete.
• **kwargs – Passed to rethinkdb.delete

Returns:

The result of RethinkDB delete.

doc(value)

Return a document instance populated from a dict. Does not save document before returning.

Parameters:value (dict) – The value to use for the document. Should conform to document_class’s schema. Returns:Document instance.

document_class

alias of Document

drop_table()

Delete the database table for this collection. Sends pre_table_deletion and post_table_deletion signals.

exposed_methods = {}

file_storage = None

help(out=None, initial_heading_level=0)

Return full reStructuredText help for this class

indexes = []

json(docs)

name = 'collection'

primary_key = 'id'

private = False

q(query)

Perform a query on this collection’s database connection.

Parameters:query (ReQL) – Should be a RethinkDB query that returns documents for this collection. Yields:Document instances.

relations = []

save(docs, **kwargs)

Save a document or list of documents to the database.

Parameters:

• docs (Document or [Document] or [dict]) – List of documents to save.
• **kwargs – Passed to rethinkdb.save

Returns:

The result of the RethinkDB save.

schema = None

schema_url

slug = None

suite

table

title = None

url

validator(value)

Override this method to do extra validation above and beyond a simple schema check.

Parameters:value (Document) – The value to validate. Returns:bool Raises:ValidationError if the document fails to validate.

exception sondra.collection.CollectionException

Bases: builtins.Exception

Represents a misconfiguration in a Collection class definition

class sondra.collection.CollectionMetaclass(name, bases, nmspc)

Bases: abc.ABCMeta

The metaclass sets name and schema and registers this collection with an application.

The schema description is updated with the docstring of the concrete collection class. The title is set to the name of the class, if it is not already set.

This metaclass also post-processes inheritance, so that:

• definitions from base classes are included in subclasses.
• exposed methods in base classes are included in subclasses.