ORM – object relational mapping

sf – ORM session factory

Module sf defines SessionFactory class which is central point for your ORM mapping and SQL database access.

class summer.sf.SessionFactory(uri: str, echo: bool, autoflush: bool, autocommit: bool)[source]

Bases: object

Thread safe SQLAlchemy session provider.

class Local[source]

Bases: _thread._local

Thread local session wrapper.

SessionFactory.__init__(uri: str, echo: bool, autoflush: bool, autocommit: bool)[source]

Creates SessionFactory instance.

Parameters:
  • uri (str) – SQLAlchemy connection string (including username and password)
  • echo (bool) – print out SQL commands
  • autoflush (bool) – whether autoflush is enabled (if unsure, set to True)
  • autocommit (bool) – whether autocommit is enabled (if unsure set to False)
SessionFactory.set_table_definitions(table_definitions)[source]

Sets table definitons.

See summer.context.Context.orm_init() method.

SessionFactory.set_class_mappings(class_mappings)[source]

Sets class mappings.

See summer.context.Context.orm_init() method.

SessionFactory.create_schema()[source]

Create database schema using SQLAlchemy. Call once table_definitions are set.

SessionFactory.get_session()[source]

Get current thread-local SQLAlchemy session wrapper (creating one, if non-exististent).

Returns:existing or just created SQLAlchemy session wrapper
Return type:SessionFactory.Local
SessionFactory.get_sqlalchemy_session() → sqlalchemy.orm.session.Session[source]

Get current SQLAlchemy session.

See get_session() method.

Returns:existing of just created SQLAlchemy session.
Return type:Session
SessionFactory.__weakref__

list of weak references to the object (if defined)

class summer.sf.AbstractTableDefinitions[source]

Bases: object

Container for SQLAlchemy table definitions. Registers itself at session factory. A callback class – use to provide table definitions to ORM.

See summer.context.Context.orm_init() method.

define_tables(session_factory: summer.sf.SessionFactory)[source]

Override in subclasses to define database tables.

__weakref__

list of weak references to the object (if defined)

class summer.sf.AbstractClassMappings[source]

Bases: object

Container for SQLAlchemy mappings. Registers itself at session factory. A callback class – use to provide class mappings to ORM.

See summer.context.Context.orm_init() method.

create_mappings(session_factory: summer.sf.SessionFactory)[source]

Override in subclasses to define mappings (tables to ORM classes – entities).

__weakref__

list of weak references to the object (if defined)

dao – ORM data access object support

Provides DAO support.

Base Dao class provides access to virtual Dao.session attribute. Inside any DAO object subclassed from Dao you can access current (thread-bound) SQLAlchemy session simply by accessing Dao.session.

Much more interesting is EntityDao class which is inteded to be used as a base DAO class for your summer.domain.Entity.

class summer.dao.Dao(session_factory: summer.sf.SessionFactory)[source]

Bases: object

Base DAO class.

Provides safe access to thread bound session through session attribute.

__init__(session_factory: summer.sf.SessionFactory)[source]

Creates Dao instance.

Parameters:session_factory (SessionFactory) – session factory to be used
__getattribute__(attrname: str)[source]

Access to virtual session attribute.

__weakref__

list of weak references to the object (if defined)

class summer.dao.EntityDao(session_factory: summer.sf.SessionFactory, clazz: type)[source]

Bases: summer.dao.Dao

Base DAO class for persistent classes subclassed from summer.domain.Entity.

Provides basic persistent operations.

Defines another virtual attribute – query – access to generic SQLAlchemy query over clazz.

__init__(session_factory: summer.sf.SessionFactory, clazz: type)[source]

Creates EntityDao instance.

Parameters:
  • session_factory (SessionFactory) – session factory intance to be passed to superclass (Dao)
  • clazz (type) – reference to class type
__getattribute__(attrname: str) → object[source]

Access to virtual query attribute.

_check_entity(entity: summer.domain.Entity)[source]

Check if entity is correct.

Parameters:entity (Entity) – entity instance to be checked
_get_result_list(query: sqlalchemy.orm.query.Query, query_filter: summer.domain.Filter) → list[source]

Get list of entities with filter offset applied. Useful for paging.

Parameters:
  • query (Query) – query to be executed
  • query_filter (Filter) – filter to be used for paging
Returns:

list of entities using query and paging supplied

Return type:

list

get(ident: object) → summer.domain.Entity[source]

Get entity by Entity.id attribute.

Parameters:ident (object) – primary key for Entity
Returns:entity instance or raise NoResultFound if none is found
Return type:Entity
save(entity: summer.domain.Entity) → summer.domain.Entity[source]

Save an entity.

Parameters:entity (Entity) – entity to be persisted
Returns:persisted instance
Return type:Entity
delete(entity_or_id: object) → summer.domain.Entity[source]

Delete an entity.

Parameters:entity_or_id (object) – either Entity or its primary key
Returns:just deleted entity instance
Return type:Entity
find(query_filter: summer.domain.Filter) → list[source]

Find collection of entities.

Parameters:query_filter (Filter) – filter with at least paging set
Returns:list of entities using query and paging supplied
Return type:list
get_by_uniq(col_name: str, col_value: object) → summer.domain.Entity[source]

Get entity by its unique attribute value.

Parameters:
  • col_name (str) – attribute column name
  • col_value (object) – attribute value
Returns:

entity instance or raise NoResultFound if none is found.

Return type:

Entity

get_by_uniq_or_none(col_name: str, col_value: object) → summer.domain.Entity[source]

Get entity by its unique attribute value.

Parameters:
  • col_name (str) – attribute column name
  • col_value (object) – attribute value
Returns:

entity instance or None if none is found.

Return type:

Entity

class summer.dao.CodeEntityDao(session_factory: summer.sf.SessionFactory, clazz: type)[source]

Bases: summer.dao.EntityDao

Base DAO class for persistent classes subclassed from summer.domain.CodeEntity.

__init__(session_factory: summer.sf.SessionFactory, clazz: type)[source]

Creates CodeEntityDao instance.

Parameters:
  • session_factory (SessionFactory) – session factory intance to be passed to superclass (Dao)
  • clazz (type) – reference to class type
find_map(query_filter: summer.domain.Filter) → dict[source]

Loads the objects into a map by CodeEntity.code attribute used as a map key.

query_filter (Filter): filter with at least paging set
Returns:dictionary of entities using query and paging supplied
Return type:dict

tx – programmatic transaction management

Module tx contains support for programmatic transaction management.

Declarative transaction management is defined in summer.txaop.

class summer.tx.TransactionCallback[source]

Bases: object

Callback object called from within a TransactionWrapper.

txrun(session: sqlalchemy.orm.session.Session, *args, **kwargs) → object[source]

Executed inside transaction.

This is a callback method. It is discouraged to use the *args and **kwargs magic.

Parameters:session (Session) – SQLAlchemy session
Returns:whatever you want to get returned from a transaction
Return type:object
__weakref__

list of weak references to the object (if defined)

class summer.tx.TransactionWrapper(session_factory: summer.sf.SessionFactory)[source]

Bases: object

Wraps the code it executes inside a transaction.

Caller provides a callback object (TransactionCallback instance) to be executed inside a transaction; it gets passed in the current thread-bound SQLAlchemy session.

It participates in current transaction if there is one active or creates a new one.

If exception is raised, transaction is rolled back.

__init__(session_factory: summer.sf.SessionFactory)[source]
Parameters:session_factory (SessionFactory) – session factory to be used
execute(callback: summer.tx.TransactionCallback, *args, **kwargs) → object[source]

Runs the callback provided inside transaction.

Whatever other arguments are provided, they are passed to callback.

Parameters:callback (TransactionCallback) – callback to be executed
Returns:whatever the callback returns
Return type:object
__weakref__

list of weak references to the object (if defined)

txaop – declarative transaction management

Declarative transaction management.

summer.txaop.transactional(func: function)[source]

Method decorator marking method as transactional.

Use together with TransactionAdvice and TransactionalProxy.

Methods decorated with transactional() can be run within a transaction if wrapped in TransactionalProxy.

Usually it is required to access SQLAlchemy session from within the transaction. Encouraged access to current thread-bound SQLAlchemy session is through summer.sf.SessionFactory.

Preferred way to manipulate your persistent entities is through DAO objects (summer.dao). Intended use case for this decorator is to mark such summer.dao.EntityDao methods and then access current SQLAlchemy session by using summer.dao.Dao.session from within the DAO method. Thus you can access SQLAlchemy session (and manipulate data), and still have the transaction boundaries defined on top of your business methods.

Parameters:func (types.FunctionType) – function to be decorated
class summer.txaop.TransactionAdvice(method: method, session_factory: summer.sf.SessionFactory)[source]

Bases: summer.aop.AroundMethodAdvice

Together with transactional() decorator forms a transaction aspect. Advice gets invoked if method is marked with transactional() and if object is wrapped in TransactionProxy.

__init__(method: method, session_factory: summer.sf.SessionFactory)[source]

Creates TransactionAdvice instance.

Parameters:
  • method (types.MethodType) – instance method marked by transactional() decorator
  • session_factory (SessionFactory) – session factory to be used
around(*args, **kwargs)[source]

Wraps the target method invocation within a transaction. If any exception is raised it gets re-thrown and the transaction is rolled back, see summer.tx.TransactionWrapper.

class summer.txaop.TransactionProxy(target: object, session_factory: summer.sf.SessionFactory=None)[source]

Bases: summer.aop.Proxy

Intercepts method invocations on target object with transaction logic.

It either calls the target object’s method directly or invokes the TransactionAdvice if the method is marked by transactional().

__init__(target: object, session_factory: summer.sf.SessionFactory=None)[source]

Creates the TransactionProxy instance.

Searches the target object for transactional() decorated methods. It creates a TransactionalAdvice object for each method found. Invocation of such a method means invoking a TransactionalAdvice object instead, wrapping the call with transaction.

Parameters:
  • target (object) – any object that is searched for transactional methods
  • session_factory (SessionFactory) – session factory to be used; if None, target object is searched for session_factory attribute which is used instead