ORM – object relational mapping — summer 0.7.5 documentation

# 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 providing connections to database.

class `summer.sf.` `SessionProvider`

  Bases: `object`

  Class to be used as based for providing SqlAlchemy session.

  See default implementation in `summer.sf.DefaultSessionProvider`.

  `__init__`()

    Initialize self. See help(type(self)) for accurate signature.

  property `engine`

    Get SqlAlchemy engine implementation.

    Returns

      SqlAlchemy engine implementation

    Return type

      sqlalchemy.engine.Engine

  property `metadata`

    Get SqlAlchemy metadata.

    Returns

      SqlAlchemy metadata

    Return type

      sqlalchemy.Metadata

  property `sessionmaker`

    Get SqlAlchemy session factory class.

    Returns

      SqlAlchemy session factory class

    Return type

      sqlalchemy.orm.sessionmaker

  property `declarative_base_class`

    Get SqlAlchemy declarative_base type. Mixing classical and declarative approaches is possible, if declarative_base type uses the same metadata and engine with classical approach. Creating single instance of single `summer.sf.SessionProvider` ensures it is the same.

    Returns

      SqlAlchemy declarative_base type to be used as base class for entities.

    Return type

      type

  `__weakref__`

    list of weak references to the object (if defined)

class `summer.sf.` `DefaultSessionProvider`(uri: str, autocommit: bool = False, **engine_kwargs)

  Bases: `summer.sf.SessionProvider`

  Default implementation of `summer.sf.SessionProvider`. Provides access to SqlAlchemy internal objectssession.

  See default implementation in `summer.sf.DefaultSessionProvider`.

  `__init__`(uri: str, autocommit: bool = False, **engine_kwargs)
    Parameters

      - uri (str) – SqlAlchemy’s uri (ie. connection string)

      - autocommit (bool) – SqlAlchemy’s autocommit

      - pool_recycle (int) – SqlAlchemy’s pool recycling timeout

  property `engine`

    Get SqlAlchemy engine implementation.

    Returns

      SqlAlchemy engine implementation

    Return type

      sqlalchemy.engine.Engine

  property `metadata`

    Get SqlAlchemy metadata.

    Returns

      SqlAlchemy metadata

    Return type

      sqlalchemy.Metadata

  property `sessionmaker`

    Get SqlAlchemy session factory class.

    Returns

      SqlAlchemy session factory class

    Return type

      sqlalchemy.orm.sessionmaker

  property `declarative_base_class`

    Get SqlAlchemy declarative_base type. Mixing classical and declarative approaches is possible, if declarative_base type uses the same metadata and engine with classical approach. Creating single instance of single `summer.sf.SessionProvider` ensures it is the same.

    Returns

      SqlAlchemy declarative_base type to be used as base class for entities.

    Return type

      type

class `summer.sf.` `SessionFactory`(session_provider: summer.sf.SessionProvider)

  Bases: `object`

  Thread safe SqlAlchemy session provider.

  class `Local`(engine: sqlalchemy.engine.base.Engine, sessionmaker: sqlalchemy.orm.session.sessionmaker)

    Bases: `_thread._local`

    Thread local session & connection wrapper.

    `__init__`(engine: sqlalchemy.engine.base.Engine, sessionmaker: sqlalchemy.orm.session.sessionmaker)

      Initialize self. See help(type(self)) for accurate signature.

    property `sqlalchemy_session`

      Get current SqlAlchemy session.

      Returns

        existing of just created SqlAlchemy session.

      Return type

        sqlalchemy.orm.Session

    property `autocommit`

      Delegates to `sqlalchemy_session.autocommit()`.

    property `connection`

      Use `connection.connection` to obtain Python DB API connection.

      Returns

        current thread-bound SqlAclhemy connection object corresponding to current session’s transactional state.

      Return type

        sqlalchemy.engine.Connection

    property `active`

      Get status of current SqlAlchemy transaction.

      Returns

        True if transaction is in progress, False otherwise.

      Return type

        bool

  `__init__`(session_provider: summer.sf.SessionProvider)

    Creates `SessionFactory` instance.

    Parameters

      uri (str) – SqlAlchemy connection string (including username and password)

  property `table_definitions`

    Get current table definitions.

    Returns

      current `TableDefinitions` instance

    Return type

      TableDefinitions

  property `class_mappings`

    Get current class mappings.

    Returns

      current `ClassMappings` instance

    Return type

      ClassMappings

  property `session`

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

    Returns

      existing or just created SqlAlchemy session wrapper

    Return type

      SessionFactory.Local

  property `sqlalchemy_session`

    Delegates to `SessionFactory.Local.sqlalchemy_session()`.

  property `connection`

    Delegates to `SessionFactory.Local.connection()`.

  property `dialect`

    Get SqlAlchemy dialect.

    Returns

      current SqlAlchemy dialect

    Return type

      sqlalchemy.engine.Dialect

  property `sqlite_dialect`

    SQLite is great database for testing or local access, but not designed for multi-threaded/-process applications. Sometimes it is handy to know you are using it to bypass its limitations.

    Returns

      True if running over sqlite, False otherwise.

    Return type

      bool

  `create_schema`()

    Create database schema using SqlAlchemy. Call once `table_definitions` are set.

    Use with caution – will destroy all your data!

  `__weakref__`

    list of weak references to the object (if defined)

class `summer.sf.` `AbstractTableDefinitions`

  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)

    Override in subclasses to define database tables.

  `__weakref__`

    list of weak references to the object (if defined)

class `summer.sf.` `AbstractClassMappings`

  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.

  `__weakref__`

    list of weak references to the object (if defined)

  `create_mappings`(session_factory: summer.sf.SessionFactory)

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

## dao – ORM data access object support

Provides DAO support.

Base `Dao` class provides access to `Dao.session()` and py:meth:Dao.connection properties.

That means that inside any DAO object subclassed from `Dao` you can access current (thread-bound) SqlAlchemy session simply by accessing `Dao.session()` and direct connection to database by accessing `Dao.connection()`.

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)

  Bases: `object`

  Base DAO class.

  Provides safe access to thread bound session through `session` attribute. Alternative is `get_session()`.

  `__init__`(session_factory: summer.sf.SessionFactory)

    Creates `Dao` instance.

    Parameters

      session_factory (SessionFactory) – session factory to be used

  property `session`

    Get current session (bound to current thread).

    Returns

      current `sqlalchemy.orm.Session` instance

    Return type

      Session

  property `connection`

    Get current connection (bound to current thread).

    Use `connection.connection` to obtain Python DB API 2.0 connection object.

    Returns

      current `sqlalchemy.engine.Connection` instance

    Return type

      Connection

  `__weakref__`

    list of weak references to the object (if defined)

class `summer.dao.` `EntityDao`(session_factory: summer.sf.SessionFactory, clazz: Type[E])

  Bases: `summer.dao.Dao`

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

  Provides basic persistent operations.

  Defines another property – `query()` – access to generic SqlAlchemy query over `clazz()`.

  `__init__`(session_factory: summer.sf.SessionFactory, clazz: Type[E])

    Creates `EntityDao` instance.

    Parameters

      - session_factory (SessionFactory) – session factory intance to be passed to superclass (`Dao`)

      - clazz (type) – reference to class type

  property `clazz`

    Get class type for this dao.

    Returns

      class for this `EntityDao`

    Return type

      type

  property `query`

    Get new query instance using `clazz()`.

    Returns

      query over `clazz()`

    Return type

      sqlalchemy.orm.Query

  `_check_entity`(entity: E)

    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[E]

    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) → Optional[E]

    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: E) → E

    Save an entity.

    Parameters

      entity (Entity) – entity to be persisted

    Returns

      persisted instance

    Return type

      Entity

  `merge`(entity: E) → E

    Merge an entity.

    Same as `save()`, but entity is associated with current session if it is not. For example if entity comes from another session (or thread).

    Parameters

      entity (Entity) – entity to be merged

    Returns

      persisted instance

    Return type

      Entity

  `delete`(entity_or_id: object) → E

    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[E]

    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) → E

    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) → Optional[E]

    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[T])

  Bases: `summer.dao.EntityDao`

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

  `__init__`(session_factory: summer.sf.SessionFactory, clazz: Type[T])

    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[str, T]

    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

exception `summer.dao.` `DaoException`(message: str = None, **kwargs)

  Bases: `summer.ex.ApplicationException`

  `__init__`(message: str = None, **kwargs)

    Creates `ApplicationException` instance.

    Parameters

      - message (str) – message to be printed

      - kwargs – keyword arguments are printed as are, suitable for providing some context (current values of important variables and such.