+ +
+

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()
+
+ +
+ +
+
+ +
+ + +