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.
-
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
-
__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 overclazz
.-
__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
- session_factory (SessionFactory) – session factory intance to be
passed to superclass
(
-
_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 foundReturn 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 keyReturns: 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
-
-
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
- session_factory (SessionFactory) – session factory intance to be
passed to superclass
(
-
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
andTransactionalProxy
.Methods decorated with
transactional()
can be run within a transaction if wrapped inTransactionalProxy
.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 suchsummer.dao.EntityDao
methods and then access current SQLAlchemy session by usingsummer.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 withtransactional()
and if object is wrapped inTransactionProxy
.-
__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
- method (types.MethodType) – instance method marked by
-
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 bytransactional()
.-
__init__
(target: object, session_factory: summer.sf.SessionFactory=None)[source]¶ Creates the
TransactionProxy
instance.Searches the target object for
transactional()
decorated methods. It creates aTransactionalAdvice
object for each method found. Invocation of such a method means invoking aTransactionalAdvice
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 forsession_factory
attribute which is used instead
-