- -
-

PyAMS SQLAlchemy integration

-

pyams_alchemy package is a small package which can be used to make SQLAlchemy integration more simple.

-

The main goal of pyams_alchemy package is to define the pyams_alchemy.engine.AlchemyEngineUtility class: -this class can be stored persistently into PyAMS local site manager (see PyAMS site management) to store settings of an -SQLAlchemy engine; on user request, the pyams_alchemy.engine.get_user_session() function can be used to get -access to a new SQLAlchemy engine session matching these settings which will to be bound to current Pyramid’s -transaction.

-
-

Dynamic schema names

-

Some times you may have to be able to setup, for a given table, a schema name which is not static but can be dynamic -through a configuration option.

-

This can be done easily with the help of the pyams_alchemy.mixin.DynamicSchemaMixin which you can inherit from -in any SQLAlchemy table subclass.

-

When this is done, the schema name can be defined into Pyramid’s configuration file into a setting which is called -pyams_alchemy:{module_name}.{class_name}.schema; for example like in -pyams_alchemy:pyams_content.package.TableName.schema. If not specified, the table’s schema name can be defined in a -classic __schema__ table’s attribute.

-
-
-

Module contents

-
-
-pyams_alchemy.includeme(config)
-

Pyramid include

-
- -
-
-

Submodules

-
-

pyams_alchemy.engine module

-
-
-class pyams_alchemy.engine.AlchemyEngineUtility(name='', dsn='', echo=False, use_pool=True, pool_size=25, pool_recycle=-1, echo_pool=False, encoding='utf-8', convert_unicode=False, **kwargs)
-

Bases: object

-

SQLAlchemy engine utility

-
-
-clear_engine()
-
- -
-
-convert_unicode
-

Convert Unicode

-
- -
-
-dsn
-

DSN: RFC-1738 compliant URL for the database connection

-
- -
-
-echo
-

Echo SQL?: Log all SQL statements to system logger

-
- -
-
-echo_pool
-

Echo pool?: Log all pool checkouts/checkins to system logger?

-
- -
-
-encoding
-

Encoding

-
- -
-
-get_engine(use_pool=True)
-
- -
-
-name
-

Engine name: Keep empty if this engine is the default engine…

-
- -
-
-pool_recycle
-

Pool recycle time: SQLAlchemy connection recycle time (-1 for none)

-
- -
-
-pool_size
-

Pool size: SQLAlchemy connections pool size

-
- -
-
-use_pool
-

Use connections pool?: If ‘no’, collections pooling will be disabled

-
- -
- -
-
-class pyams_alchemy.engine.ConnectionCleanerThread(group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None)
-

Bases: threading.Thread

-

Background thread used to clean unused database connections

-

Each connection is referenced in CONNECTION_TIMESTAMPS mapping on checkin and is invalidated -if not being used after 5 minutes

-
-
-run()
-
- -
-
-timeout = 300
-
- -
- -
-
-class pyams_alchemy.engine.EnginesVocabulary(context, **kw)
-

Bases: zope.componentvocabulary.vocabulary.UtilityVocabulary

-

SQLAlchemy engines vocabulary

-
-
-interface = <InterfaceClass pyams_alchemy.interfaces.IAlchemyEngineUtility>
-
- -
-
-nameOnly = True
-
- -
- -
-
-class pyams_alchemy.engine.PersistentAlchemyEngineUtility(name='', dsn='', echo=False, use_pool=True, pool_size=25, pool_recycle=-1, echo_pool=False, encoding='utf-8', convert_unicode=False, **kwargs)
-

Bases: persistent.Persistent, pyams_alchemy.engine.AlchemyEngineUtility, zope.container.contained.Contained

-

Persistent implementation of SQLAlchemy engine utility

-
- -
-
-pyams_alchemy.engine.get_engine(engine, use_pool=True)
-

Get engine matching given utility name

-
- -
-
-pyams_alchemy.engine.get_session(engine, join=True, status='active', request=None, alias=None, twophase=True, use_zope_extension=True, use_pool=True)
-

Get a new SQLALchemy session

-

Session is stored in request and in session storage. -See get_user_session() function to get arguments documentation.

-
- -
-
-pyams_alchemy.engine.get_user_session(engine, join=True, status='active', request=None, alias=None, twophase=True, use_zope_extension=True, use_pool=True)
-

Get a new SQLAlchemy session

- --- - - - -
Parameters:
    -
  • engine (str) – name of an SQLAlchemy engine session utility; if engine is not given as a string, it is -returned as-is.
    • -
  • join (bool) – if True, session is joined to the current Pyramid transaction
    • -
  • status (str) – status of the new session; can be STATUS_ACTIVE or STATUS_READONLY
    • -
  • request – currently running request
    • -
  • alias (str) – alias to use in connections mapping for this session
    • -
  • twophase (bool) – if False, session will be isolated and not included into two-phase transactions mechanism
    • -
  • use_zope_extension (bool) – if True, use ZopeTransactionExtension scoped session
    • -
  • use_pool (bool) – if True, this session will use a pool
    • -
-
-
- -
-
-pyams_alchemy.engine.handle_added_engine(event)
-

Register new SQLAlchemy engine when added

-
- -
-
-pyams_alchemy.engine.handle_modified_engine(event)
-

Clear SQLAlchemy engine volatile attributes when modified

-
- -
-
-pyams_alchemy.engine.handle_pool_checkin(connection, record)
-

Pool connection checkin

-

Called when a connection returns to the pool. -We apply a timestamp on the connection record to be able to close it automatically -after 5 minutes without being used.

-
- -
-
-pyams_alchemy.engine.handle_pool_checkout(connection, record, proxy)
-

Pool connection checkout

-

Called when a connection is retrieved from the pool. -If the connection record is already marked, we remove it from the mapping.

-
- -
-
-pyams_alchemy.engine.handle_removed_engine(event)
-

Un-register an SQLAlchemy engine when deleted

-
- -
-
-

pyams_alchemy.loader module

-
-
-class pyams_alchemy.loader.DataLoader(source, target, entities)
-

Bases: object

-

SQLAlchemy data loader

-

This utility class is used to migrate entities from a given connection -to another one. -WARNING: actually, given entities must share the same schema name!!!

-
-
-run()
-
- -
- -
-
-

pyams_alchemy.metaconfigure module

-
-
-pyams_alchemy.metaconfigure.engine_directive(context, name='', dsn='', echo=False, use_pool=True, pool_size=25, pool_recycle=-2, echo_pool=False, encoding='utf-8', convert_unicode=False, **kwargs)
-
- -
-
-

pyams_alchemy.metadirectives module

-
-
-

pyams_alchemy.mixin module

-
-
-class pyams_alchemy.mixin.DynamicSchemaMixin
-

Bases: object

-

Dynamic schema mixin class

-

This class is used to set an entity schema name in Pyramid settings

-
-
-classmethod get_schema()
-
- -
-
-classmethod get_schema_settings_name()
-
- -
- -
-
- -
- - -