Tori Framework¶

Introduction¶

The object-relational mapping (ORM) module in Tori is designed for non-relational databases. The current version of ORM is designed only for MongoDB 2.2 or newer. There are plans for other kinds of databases but there are not enough resources.

Getting Started¶

The chapter illustrates how to define entities and set up an entity manager.

from tori.db.entity import entity

# Alternatively, @entity('name_of_collection') is to set the name of the collection.
@entity
class Character(object):
    def __init__(self, name, team=None):
        self.name = name
        self.team = None

@entity
class Team(Object):
    def __init__(self, name):
        self.name = name

from tori.db.manager import ManagerFactory

manager_factory = ManagerFactory()
manager_factory.set('ff_game', 'mongodb://db_host/db_name')

entity_manager = manager_factory.get('ff_game')

Basic Usage¶

Suppose we have:

session   = entity_manager.open_session()
char_repo = session.repository(Character)

ramza = Character('Ramza')
alma  = Character('Alma')

character_repo.post(ramza)
character_repo.post(alma)

query      = char_repo.new_criteria('c')
characters = char_repo.find(query)

for character in characters:
    print('{}: {}'.format(character.id, character.name))

1: Ramza
2: Alma

query = char_repo.new_criteria('c')
query.expect('c.name = :name')
query.define('name', 'Ramza')

characters = char_repo.find(query)

for character in characters:
    print('{}: {}'.format(character.id, character.name))

1: Ramza

alma = char_repo.get(2)

alma = collection.get(2)

alma.name = 'Luso'

char_repo.put(character)

char_repo.delete(alma)

Working with Associations¶

This chapter introduces association mappings which directly use object IDs to refer to the corresponding objects.

Tori only uses decorators (or annotations in some other languages) to define the association mapping.

Instead of working with the object IDs directly, you will always work with references to objects:

• A reference to a single object is represented by object IDs.
• A collection of objects is represented by many object IDs pointing to the object holding the collection

There are two sections in this chapter:

• types of associations
• options for associations

from tori.db.entity import entity
from tori.db.mapper import link, AssociationType as t, CascadingType as c

Owner (1) ----- (1) Restaurant

Owner (1) <--x- (1) Restaurant

@entity
class Owner(object):
    def __init__(self, name):
        self.name  = name

@link(
    target      = 'sampleapp.model.Owner',
    mapped_by   = 'owner',
    association = t.ONE_TO_ONE
)
@entity
class Restaurant(object):
    def __init__(self, name, owner):
        self.name  = name
        self.owner = owner

// collection: owner
{'_id': 'o-1', 'name': 'siamese'}

// collection: restaurant
{'_id': 'rest-1', 'name': 'green curry', 'owner': 'o-1'}

Owner (1) <---> (1) Restaurant

@link(
    target      = 'sampleapp.model.Restaurant'
    inverted_by = 'owner',
    mapped_by   = 'restaurant',
    association = t.ONE_TO_ONE
)
@entity
class Owner(object):
    def __init__(self, name, restaurant):
        self.name       = name
        self.restaurant = restaurant

Customer (1) ----- (0..n) Reward

Customer (1) <--x- (0..n) Reward

@entity
class Customer(object):
    def __init__(self, name):
        self.name    = name

@link(
    target      = 'sampleapp.model.Customer',
    mapped_by   = 'customer',
    association = t.MANY_TO_ONE
)
@entity
class Reward(object):
    def __init__(self, point, customer):
        self.point    = point
        self.customer = customer

// collection: customer
{'_id': 'c-1', 'name': 'panda'}

// collection: reward
{'_id': 'rew-1', 'point': 2, 'customer': 'c-1'}
{'_id': 'rew-2', 'point': 13, 'customer': 'c-1'}

Customer (1) <---> (0..n) Reward

@link(
    target      = 'sampleapp.model.Reward',
    inverted_by = 'customer',
    mapped_by   = 'rewards',
    association = t.ONE_TO_MANY
)
@entity
class Customer(object):
    def __init__(self, name, rewards):
        self.name    = name
        self.rewards = rewards

Customer (1) -x--> (0..n) Reward

@link(
    target      = 'sampleapp.model.Reward',
    mapped_by   = 'rewards',
    association = t.ONE_TO_MANY
)
@entity
class Customer(object):
    def __init__(self, name, rewards):
        self.name    = name
        self.rewards = rewards

@entity
class Reward(object):
    def __init__(self, point):
        self.point = point

// collection: customer
{'_id': 'c-1', 'name': 'panda', 'reward': ['rew-1', 'rew-2']}

// collection: reward
{'_id': 'rew-1', 'point': 2}
{'_id': 'rew-2', 'point': 13}

Teacher (*) ----- (*) Student

Teacher (*) <--x- (*) Student

@entity('teachers')
class Teacher(object):
    def __init__(self, name):
        self.name = name

@link(
    mapped_by   = 'teachers',
    target      = Teacher,
    association = AssociationType.MANY_TO_MANY,
    cascading   = [c.DELETE, c.PERSIST]
)
@entity('students')
class Student(object):
    def __init__(self, name, teachers=[]):
        self.name     = name
        self.teachers = teachers

// db.students.find()
{'_id': 1, 'name': 'Shirou'}
{'_id': 2, 'name': 'Shun'}
{'_id': 3, 'name': 'Bob'}

// db.teachers.find()
{'_id': 1, 'name': 'John McCain'}
{'_id': 2, 'name': 'Onizuka'}

// db.students_teachers.find() // -> join collection
{'_id': 1, 'origin': 1, 'destination': 1}
{'_id': 2, 'origin': 1, 'destination': 2}
{'_id': 3, 'origin': 2, 'destination': 2}
{'_id': 4, 'origin': 3, 'destination': 1}

query = reward_repository.new_criteria('r')
query.join('r.customer', 'c')
query.expect('c.name = "Bob"')

rewards = reward_repository.find(query)

Handling transactions (sessions)¶

Similar to Sessions in SQLAlchemy.

In the most general sense, the session establishes all conversations with the database and represents a “holding zone” for all the objects which you’ve loaded or associated with it during its lifespan. It provides the entrypoint to acquire a tori.db.orm.repository.Repository object, which sends queries to the database using the current database connection of the session (tori.db.orm.session.Session), populating result rows into objects that are then stored in the session, inside a structure called the identity map (internally being the combination of “the record map” and “the object ID map”) - a data structure that maintains unique copies of each object, where “unique” means “only one object with a particular primary key”.

The session begins in an essentially stateless form. Once queries are issued or other objects are persisted with it, it requests a connection resource from an manager that is associated with the session itself. This connection represents an ongoing transaction, which remains in effect until the session is instructed to commit.

All changes to objects maintained by a session are tracked - before the database is queried again or before the current transaction is committed, it flushes all pending changes to the database. This is known as the Unit of Work pattern.

When using a session, it’s important to note that the objects which are associated with it are proxy objects (tori.db.orm.common.ProxyObject) to the transaction being held by the session - there are a variety of events that will cause objects to re-access the database in order to keep synchronized. It is possible to “detach” objects from a session, and to continue using them, though this practice has its caveats. It’s intended that usually, you’d re-associate detached objects with another Session when you want to work with them again, so that they can resume their normal task of representing database state.

from tori.db.manager import ManagerFactory

manager_factory = ManagerFactory()
manager_factory.set('default', 'mongodb://db_host/db_name')

entity_manager = manager_factory.get('default')

session = entity_manager.open_session()

repo = session.collection(User)

query = repo.new_criteria('c')
query.expect('c.name = :name')
query.define('name', 'Bob')

bob = repo.find(query)

print(bob.address)

Bangkok, Thailand

bob.address = 'London, UK'
session.persist(bob)

session.delete(bob)

session.refresh(bob)

session.flush()

Cascading¶

This is the one toughest section to write.

MongoDB, as far as everyone knows, does not support cascading operations like the way MySQL and other vendors do with cascading deletion. Nevertheless, Tori supports cascading through the database abstraction layer (DBAL).

Here is a sample scenario.

Suppose I have two types of objects: a sport team and a player. When a team is updated, removed or refreshed, the associated player should be treated the same way as the team. Here is a sample code.

from tori.db.entity import entity
from tori.db.mapper import CascadingType as c

@entity
class Player(object):
    pass # omit the usual setup decribed in the basic usage.

@link(
    target=Player,
    mapped_by='player',
    cascading=[c.PERSIST, c.DELETE, c.REFRESH]
)
@entity
class Team(object):
    pass # omit the usual setup decribed in the basic usage.

Now, whatever operation is used on a Team entity, associated Player entites are subject to the same operation.

tori.db.common¶

class tori.db.common.ProxyCollection(session, origin, guide)¶

Proxy Collection

This collection is extended from the built-in class list, designed to only load the associated data whenever is required.

Parameters:	session (tori.db.session.Session) – the managed session origin (object) – the origin of the association guide (tori.db.mapper.RelatingGuide) – the relational guide

Note

To replace with criteria and driver

reload()¶

Reload the data list

Warning

This method is not recommended to be called directly. Use tori.db.session.Session.refresh() on the owned object instead.

class tori.db.common.ProxyFactory¶

Proxy Factory

This factory is to create a proxy object.

Parameters:	session (tori.db.session.Session) – the managed session id – the object ID mapping_guide (tori.db.mapper.RelatingGuide) – the relational guide

class tori.db.common.ProxyObject(session, cls, object_id, read_only, cascading_options, is_reverse_proxy)¶

Proxy Collection

This class is designed to only load the entity whenever the data access is required.

Parameters:	session (tori.db.session.Session) – the managed session cls (type) – the class to map the data object_id – the object ID read_only (bool) – the read-only flag cascading_options (list or tuple) – the cascading options is_reverse_proxy (bool) – the reverse proxy flag

class tori.db.common.PseudoObjectId(oid=None)¶

Pseudo Object ID

This class extends from bson.objectid.ObjectId.

This is used to differentiate stored entities and new entities.

class tori.db.common.Serializer(max_depth=2, mode='forgiven')¶

Object Serializer for Entity

encode(data, stack_depth=0, convert_object_id_to_str=False)¶

Encode data into dictionary and list.

Parameters:	data – the data to encode stack_depth – traversal depth limit convert_object_id_to_str – flag to convert object ID into string

tori.db.criteria¶

tori.db.driver¶

class tori.db.driver.interface.DialectInterface¶

Dialect interface

It is used to translate a generic query into a native query.

get_alias_to_native_query_map(query)¶

Retrieve a map from alias to native query.

Parameters:	tori.db.criteria.Query – the query object
Return type:	dict

get_iterating_constrains(query)¶

Retrieve the query constrains.

Raises:	NotImplemented – only if the interface is not overridden.

get_native_operand(generic_operand)¶

Translate a generic operand into a corresponding native operand.

Parameters:	generic_operand – a generic operand
Returns:	a native operand
Return type:	str

process_join_conditions(alias_to_conditions_map, alias, join_config, parent_alias)¶

Process the join conditions.

Parameters:	alias_to_conditions_map (dict) – a alias-to-conditions map join_config (dict) – a join config map alias (str) – an alias of the given join map parent_alias (str) – the parent alias of the given join map
Raises:	NotImplemented – only if the interface is not overridden.

process_non_join_conditions(alias_to_conditions_map, definition_map, left, right, operand)¶

Process the non-join conditions.

Parameters:	alias_to_conditions_map (dict) – a alias-to-conditions map definition_map (dict) – a parameter-to-value map left (tori.db.expression.ExpressionPart) – the left expression right (tori.db.expression.ExpressionPart) – the right expression operand – the native operand
Raises:	NotImplemented – only if the interface is not overridden.

class tori.db.driver.interface.DriverInterface(config, dialect)¶

The abstract driver interface

Parameters:	config (dict) – the configuration used to initialize the database connection / client dialect (tori.db.driver.interface.DialectInterface) – the corresponding dialect

client¶

Driver Connection / Client

collection(name)¶

Low-level Collection-class API

Returns:	the low-level collection-class API
Raises:	NotImplemented – only if the interface is not overridden.

config¶

Driver configuration

connect(config)¶

Connect the client to the server.

Raises:	NotImplemented – only if the interface is not overridden.

database_name¶

The name of provisioned database

db(name)¶

Low-level Database-class API

Returns:	the low-level database-class API
Raises:	NotImplemented – only if the interface is not overridden.

dialect¶

Driver dialect

disconnect()¶

Disconnect the client.

Raises:	NotImplemented – only if the interface is not overridden.

index_count()¶

Retrieve the number of indexes.

Raises:	NotImplemented – only if the interface is not overridden.

indice()¶

Retrieve the indice.

Raises:	NotImplemented – only if the interface is not overridden.

insert(collection_name, data)¶

Low-level insert function

Raises:	NotImplemented – only if the interface is not overridden.

class tori.db.driver.interface.QueryIteration(alias, native_query)¶

Driver Query Iteration

This is a metadata class representing an iteration in complex queries.

Parameters:	alias (str) – the alias of the rewritten target native_query (dict) – the native query for a specific engine

Note

Internal use only

class tori.db.driver.interface.QuerySequence¶

Driver Query Sequence

The collection represents the sequence of sub queries.

add(iteration)¶

Append the the iteration

Parameters:	iteration (tori.db.driver.interface.QueryIteration) – the query iteration

each()¶

Get the sequence iterator.

exception tori.db.driver.mongodriver.InvalidExpressionError¶

MongoDB-specific Invalid Expression Error

exception tori.db.driver.mongodriver.UnsupportedExpressionError¶

MongoDB-specific Unsupported Expression Error

This is due to that the expression may be unsafe (e.g., 1 = 2) or result in unnecessary complex computation (e.g., e.mobile_phone = e.home_phone).

tori.db.entity¶

class tori.db.entity.BasicAssociation(origin, destination)¶

Basic Association

Parameters:	origin (object) – The origin of the association destination (object) – The destination (endpoint) of the association

Note

This class is used automatically by the association mapper.

class tori.db.entity.Entity(**attributes)¶

Dynamic-attribute Basic Entity

Parameters:	attributes (dict) – key-value dictionary

Here is an example on how to use this class.

@entity
class Note(Entity): pass

class tori.db.entity.Index(field_map, unique=False)¶

Parameters:	field_map (dict) – the map of field to index type unique (bool) – the unique flag

Unless a field is not in the map of fixed orders, the index will instruct the repository to ensure all combinations of indexes are defined whenever is necessary.

tori.db.entity.entity(*args, **kwargs)¶

Entity decorator

Parameters:	collection_name (str) – the name of the collection
Returns:	the decorated object
Return type:	object

tori.db.entity.prepare_entity_class(cls, collection_name=None, indexes=[])¶

Create a entity class

Parameters:	cls (object) – the document class collection_name (str) – the name of the corresponding collection where the default is the lowercase version of the name of the given class (cls)

The object decorated with this decorator will be automatically provided with a few additional attributes.

Attribute	Access	Description	Read	Write
id	Instance	Document Identifier	Yes	Yes, ONLY id is undefined.
__t3_orm_meta__	Static	Tori 3’s Metadata	Yes	ONLY the property of the metadata
__session__	Instance	DB Session	Yes	Yes, but NOT recommended.

The following attributes might stay around but are deprecated as soon as the stable Tori 3.0 is released.

Attribute	Access	Description	Read	Write
__collection_name__	Static	Collection Name	Yes	Yes, but NOT recommended.
__relational_map__	Static	Relational Map	Yes	Yes, but NOT recommended.
__indexes__	Static	Indexing List	Yes	Yes, but NOT recommended.

__session__ is used to resolve the managing rights in case of using multiple sessions simutaneously.

For example,

@entity
class Note(object):
    def __init__(self, content, title=''):
        self.content = content
        self.title   = title

where the collection name is automatically defined as “note”.

Changed in version 3.0: The way Tori stores metadata objects in __collection_name__, __relational_map__ and __indexes__ are now ignored by the ORM in favour of __t3_orm_meta__ which is an entity metadata object.

This change is made to allow easier future development.

Tip

You can define it as “notes” by replacing @entity with @entity('notes').

tori.db.exception¶

exception tori.db.exception.DuplicatedRelationalMapping¶

Exception thrown when the property is already mapped.

exception tori.db.exception.EntityAlreadyRecognized¶

Warning raised when the entity with either a designated ID or a designated session is provided to Repository.post

exception tori.db.exception.EntityNotRecognized¶

Warning raised when the entity without either a designated ID or a designated session is provided to Repository.put or Repository.delete

exception tori.db.exception.IntegrityConstraintError¶

Runtime Error raised when the given value violates a integrity constraint.

exception tori.db.exception.InvalidUrlError¶

Invalid DB URL Error

exception tori.db.exception.LockedIdException¶

Exception thrown when the ID is tempted to change.

exception tori.db.exception.MissingObjectIdException¶

Exception raised when the object Id is not specified during data retrieval.

exception tori.db.exception.NonRefreshableEntity¶

Exception thrown when the UOW attempts to refresh a non-refreshable entity

exception tori.db.exception.ReadOnlyProxyException¶

Exception raised when the proxy is for read only.

exception tori.db.exception.UOWRepeatedRegistrationError¶

Error thrown when the given reference is already registered as a new reference or already existed.

exception tori.db.exception.UOWUnknownRecordError¶

Error thrown when the given reference is already registered as a new reference or already existed.

exception tori.db.exception.UOWUpdateError¶

Error thrown when the given reference is already registered as a new reference or already existed.

exception tori.db.exception.UnavailableCollectionException¶

Exception thrown when the collection is not available.

exception tori.db.exception.UnknownDriverError¶

Unknown Driver Error

exception tori.db.exception.UnsupportedRepositoryReferenceError¶

Unsupported Repository Reference Error

tori.db.expression¶

class tori.db.expression.Criteria¶

Expression Criteria

Support operands: =, <=, <, >, >=, in, like (SQL-like string pattern), rlike (Regular-expression pattern), indexed with (only for Riak)

class tori.db.expression.Expression(left, operand, right)¶

Query Expression

Parameters:	left (tori.db.expression.ExpressionPart) – the left part right (tori.db.expression.ExpressionPart) – the right part operand (str) – the generic operand

class tori.db.expression.ExpressionPart(original, kind, value, alias)¶

Query Expression

Parameters:	original (str) – the original query kind (str) – the type of the part value – the parameter value only for a data part alias (str) – the entity alias for a property part or the name of the parameter of a parameter part

class tori.db.expression.ExpressionSet(expressions)¶

Representation of Analyzed Expression

exception tori.db.expression.InvalidExpressionError¶

Generic Invalid Expression Error

tori.db.fixture¶

class tori.db.fixture.Fixture(repository)¶

Foundation of the council

Note

this must be used at most once.

Warning

this class is not tested.

set(kind, fixtures)¶

Define the fixtures.

Parameters:	kind (unicode|str) – a string represent the kind fixtures (dict) – the data dictionary keyed by the alias

fixture = Fixture()

fixture.set(
    'council.security.model.Provider',
    {
        'ldap': { 'name': 'ldap' }
    }
)
fixture.set(
    'council.user.model.User', {
        'admin': { 'name': 'Juti Noppornpitak' }
    }
)
fixture.set(
    'council.security.model.Credential',
    {
        'shiroyuki': {
            'login':    'admin',
            'user':     'proxy/council.user.model.User/admin',
            'provider': 'proxy/council.security.model.Provider/ldap'
        }
    }
)

tori.db.manager¶

class tori.db.manager.Manager(driver)¶

Entity Manager

Parameters:	driver (tori.db.driver.interface.DriverInterface) – the driver interface

close_session(id_or_session)¶

Close the managed session

Warning

This method is designed to bypass errors when the given ID is unavailable or already closed.

driver¶

Driver API

Return type:	tori.db.driver.interface.DriverInterface

open_session(id=None, supervised=False)¶

Open a session

Parameters:	id – the session ID supervised (bool) – the flag to indicate that the opening session will be observed and supervised by the manager. This allows the session to be reused by multiple components. However, it is not thread-safe. It is disabled by default.

tori.db.mapper¶

class tori.db.mapper.AssociationFactory(origin, guide, cascading_options, is_reverse_mapping)¶

Association Factory

class_name¶

Auto-generated Association Class Name

Return type:	str

Note

This is a read-only property.

cls¶

Auto-generated Association Class

Return type:	type

Note

This is a read-only property.

collection_name¶

Auto-generated Collection Name

Return type:	str

Note

This is a read-only property.

destination¶

Destination

Return type:	type

origin¶

Origin

Return type:	type

class tori.db.mapper.AssociationType¶

Association Type

AUTO_DETECT = 1¶

Auto detection (default, disabled and raising exception)

MANY_TO_MANY = 5¶

Many-to-many association mode

MANY_TO_ONE = 4¶

Many-to-one association mode

ONE_TO_MANY = 3¶

One-to-many association mode

ONE_TO_ONE = 2¶

One-to-one association mode

static known_type(t)¶

Check if it is a known type

Parameters:	t (int) – type
Returns:	True if it is a known type.
Return type:	bool

class tori.db.mapper.BasicGuide(target_class, association)¶

Basic Relation Guide

This class is abstract and used with the relational map of the given entity class.

Parameters:	target_class (object) – the target class or class name (e.g., acme.entity.User) association (int) – the type of association

target_class¶

The target class

Return type:	type

class tori.db.mapper.CascadingType¶

Cascading Type

DELETE = 2¶

Cascade on delete operation

DETACH = 4¶

Cascade on detach operation

Note

Supported in Tori 2.2

MERGE = 3¶

Cascade on merge operation

Note

Supported in Tori 2.2

PERSIST = 1¶

Cascade on persist operation

REFRESH = 5¶

Cascade on refresh operation

class tori.db.mapper.RelatingGuide(entity_class, target_class, inverted_by, association, read_only, cascading_options)¶

Relation Guide

This class is used with the relational map of the given entity class.

Parameters:

entity_class (type) – the reference of the current class mapped_by (str) – the name of property of the current class target_class (type) – the target class or class name (e.g., acme.entity.User) inverted_by (str) – the name of property of the target class association (int) – the type of association read_only (bool) – the flag to indicate whether this is for read only. cascading_options (list or tuple) – the list of actions on cascading

tori.db.mapper.link(mapped_by=None, target=None, inverted_by=None, association=1, read_only=False, cascading=[])¶

Association decorator

New in version 2.1.

This is to map a property of the current class to the target class.

Parameters:	mapped_by (str) – the name of property of the current class target (type) – the target class or class name (e.g., acme.entity.User) inverted_by (str) – the name of property of the target class association (int) – the type of association read_only (bool) – the flag to indicate whether this is for read only. cascading (list or tuple) – the list of actions on cascading
Returns:	the decorated class
Return type:	type

Tip

If target is not defined, the default target will be the reference class.

tori.db.mapper.map(cls, mapped_by=None, target=None, inverted_by=None, association=1, read_only=False, cascading=[])¶

Map the given class property to the target class.

New in version 2.1.

Parameters:

cls (type) – the reference of the current class mapped_by (str) – the name of property of the current class target (type) – the target class or class name (e.g., acme.entity.User) inverted_by (str) – the name of property of the target class association (int) – the type of association read_only (bool) – the flag to indicate whether this is for read only. cascading (list or tuple) – the list of actions on cascading

tori.db.metadata¶

class tori.db.metadata.entity.EntityMetadata¶

Entity Metadata

cls¶

Entity Class

collection_name¶

Collection / Bucket / Table Name

index_list¶

Index List

relational_map¶

Relational Map

class tori.db.metadata.helper.EntityMetadataHelper¶

Entity Metadata Helper

static extract()¶

Extract the metadata of the given class

Parameters:	cls (type) – the entity class
Return type:	tori.db.metadata.entity.EntityMetadata

static hasMetadata()¶

Check if the given class cls has a metadata

Parameters:	cls (type) – the entity class
Return type:	bool

static imprint(collection_name, indexes)¶

Imprint the entity metadata to the class (type)

Parameters:	cls (type) – the entity class collection_name (str) – the name of the collection (known as table, bucket etc.) indexes (list) – the list of indexes

tori.db.repository¶

class tori.db.repository.Repository(session, representing_class)¶

Repository (Entity AbstractRepository) for Mongo DB

Parameters:	session (tori.db.session.Session) – the entity manager representing_class (type) – the representing class

A repository may automatically attempt to create an index if auto_index() define the auto-index flag. Please note that the auto-index feature is only invoked when it tries to use a criteria with sorting or filtering with a certain type of conditions.

auto_index(auto_index)¶

Enable the auto-index feature

Parameters:	auto_index (bool) – the index flag

count(criteria)¶

Count the number of entities satisfied the given criteria

Parameters:	criteria (tori.db.criteria.Query) – the search criteria
Return type:	int

find(criteria, force_loading=False)¶

Find entity with criteria

Parameters:	criteria (tori.db.criteria.Query) – the search criteria force_loading (bool) – the flag to force loading all references behind the proxy
Returns:	the result based on the given criteria
Return type:	object or list of objects

index(index, force_index=False)¶

Index data

Parameters:	index (list, tori.db.entity.Index or str) – the index force_index (bool) – force indexing if necessary

name¶

Collection name

Return type:	str

new(**attributes)¶

Create a new document/entity

Parameters:	attributes – attribute map
Returns:	object

Note

This method deal with data mapping.

new_criteria(alias='e')¶

Create a criteria

Return type:	tori.db.criteria.Query

session¶

Session

Return type:	tori.db.session.Session

setup_index()¶

Set up index for the entity based on the entity and link decorators

tori.db.session¶

class tori.db.session.Session(driver)¶

Database Session

Parameters:	database_name – the database name driver – the driver API

apply_relational_map(entity)¶

Wire connections according to the relational map

collection(entity_class)¶

Alias to repository()

Deprecated since version 2.2.

delete(*entities)¶

Delete entities

Parameters:	entities (type of list of type) – one or more entities

flush()¶

Flush all changes of the session.

persist(*entities)¶

Persist entities

Parameters:	entities (type of list of type) – one or more entities

refresh(*entities)¶

Refresh entities

Parameters:	entities (type of list of type) – one or more entities

register_class(entity_class)¶

Register the entity class

Parameters:	entity_class (type) – the class of document/entity
Return type:	tori.db.repository.Repository

Note

This is for internal operation only. As it seems to be just a residual from the prototype stage, the follow-up investigation in order to remove the method will be for Tori 3.1.

repositories()¶

Retrieve the list of collections

Return type:	list

repository(reference)¶

Retrieve the collection

Parameters:	reference – the entity class or entity metadata of the target repository / collection
Return type:	tori.db.repository.Repository

tori.db.uow¶

class tori.db.uow.DependencyNode(record)¶

Dependency Node

This is designed to be bi-directional to maximize flexibility on traversing the graph.

class tori.db.uow.UnitOfWork(entity_manager)¶

Unit of Work

This Unit of Work (UOW) is designed specifically for non-relational databases.

Note

It is the design decision to make sub-commit methods available so that when it is used with Imagination Framework, the other Imagination entity may intercept before or after actually committing data. In the other word, Imagination Framework acts as an event controller for any actions (public methods) of this class.

refresh(entity)¶

Refresh the entity

Note

This method

Parameters:	entity (object) – the target entity

register_clean(entity)¶

Register the entity with the clean bit

Parameters:	entity (object) – the entity to register

register_deleted(entity)¶

Register the entity with the removal bit

Parameters:	entity (object) – the entity to register

register_dirty(entity)¶

Register the entity with the dirty bit

Parameters:	entity (object) – the entity to register

register_new(entity)¶

Register a new entity

Parameters:	entity (object) – the entity to register