sqlalchemy.orm
==============
+.. module:: sqlalchemy.orm
+
.. toctree::
:glob:
Querying
========
-.. module:: sqlalchemy.orm
+.. module:: sqlalchemy.orm.query
+
+.. currentmodule:: sqlalchemy.orm
The Query Object
----------------
Events
-------
+======
.. automodule:: sqlalchemy.event
+
+.. autofunction:: sqlalchemy.event.listen
+
+Connection Pool Events
+----------------------
+
+.. autoclass:: sqlalchemy.pool.PoolEvents
:members:
+Connection Events
+------------------------
+
+.. autoclass:: sqlalchemy.engine.base.EngineEvents
+ :members:
sqlalchemy
==========
+.. module:: sqlalchemy
+
.. toctree::
:glob:
-Interfaces
-----------
+Interfaces (Deprecated)
+------------------------
SQLAlchemy's interface system is now deprecated, and has been
superceded by a more flexible and consistent event dispatch
def _do_commit(self):
self.connection._commit_twophase_impl(self.xid, self._is_prepared)
+class EngineEvents(event.Events):
+ """Available events for :class:`.Engine`."""
+
+ @classmethod
+ def listen(cls, fn, identifier, target):
+ if issubclass(target.Connection, Connection):
+ target.Connection = _proxy_connection_cls(
+ Connection,
+ target.events)
+ event.Events.listen(fn, identifier, target)
+
+ def on_execute(self, conn, execute, clauseelement, *multiparams, **params):
+ """Intercept high level execute() events."""
+
+ def on_cursor_execute(self, conn, execute, cursor, statement,
+ parameters, context, executemany):
+ """Intercept low-level cursor execute() events."""
+
+ def on_begin(self, conn, begin):
+ """Intercept begin() events."""
+
+ def on_rollback(self, conn, rollback):
+ """Intercept rollback() events."""
+
+ def on_commit(self, conn, commit):
+ """Intercept commit() events."""
+
+ def on_savepoint(self, conn, savepoint, name=None):
+ """Intercept savepoint() events."""
+
+ def on_rollback_savepoint(self, conn, rollback_savepoint, name, context):
+ """Intercept rollback_savepoint() events."""
+
+ def on_release_savepoint(self, conn, release_savepoint, name, context):
+ """Intercept release_savepoint() events."""
+
+ def on_begin_twophase(self, conn, begin_twophase, xid):
+ """Intercept begin_twophase() events."""
+
+ def on_prepare_twophase(self, conn, prepare_twophase, xid):
+ """Intercept prepare_twophase() events."""
+
+ def on_rollback_twophase(self, conn, rollback_twophase, xid, is_prepared):
+ """Intercept rollback_twophase() events."""
+
+ def on_commit_twophase(self, conn, commit_twophase, xid, is_prepared):
+ """Intercept commit_twophase() events."""
+
class Engine(Connectable, log.Identified):
"""
Connects a :class:`~sqlalchemy.pool.Pool` and
if execution_options:
self.update_execution_options(**execution_options)
- class events(event.Events):
- @classmethod
- def listen(cls, fn, identifier, target):
- if issubclass(target.Connection, Connection):
- target.Connection = _proxy_connection_cls(
- Connection,
- target.events)
- event.Events.listen(fn, identifier, target)
- def on_execute(self, conn, execute, clauseelement, *multiparams, **params):
- """Intercept high level execute() events."""
-
- def on_cursor_execute(self, conn, execute, cursor, statement,
- parameters, context, executemany):
- """Intercept low-level cursor execute() events."""
-
- def on_begin(self, conn, begin):
- """Intercept begin() events."""
-
- def on_rollback(self, conn, rollback):
- """Intercept rollback() events."""
-
- def on_commit(self, conn, commit):
- """Intercept commit() events."""
-
- def on_savepoint(self, conn, savepoint, name=None):
- """Intercept savepoint() events."""
-
- def on_rollback_savepoint(self, conn, rollback_savepoint, name, context):
- """Intercept rollback_savepoint() events."""
-
- def on_release_savepoint(self, conn, release_savepoint, name, context):
- """Intercept release_savepoint() events."""
-
- def on_begin_twophase(self, conn, begin_twophase, xid):
- """Intercept begin_twophase() events."""
-
- def on_prepare_twophase(self, conn, prepare_twophase, xid):
- """Intercept prepare_twophase() events."""
-
- def on_rollback_twophase(self, conn, rollback_twophase, xid, is_prepared):
- """Intercept rollback_twophase() events."""
-
- def on_commit_twophase(self, conn, commit_twophase, xid, is_prepared):
- """Intercept commit_twophase() events."""
- events = event.dispatcher(events)
+ events = event.dispatcher(EngineEvents)
def update_execution_options(self, **opt):
"""update the execution_options dictionary of this :class:`Engine`.
"""
-The event system handles all events throughout the sqlalchemy
-and sqlalchemy.orm packages.
+The event system handles all events throughout the :mod:`sqlalchemy`
+and :mod:`sqlalchemy.orm` packages.
-Event specifications:
-
-:attr:`sqlalchemy.pool.Pool.events`
"""
self._clslevel = util.defaultdict(list)
def append(self, obj, target):
- assert isinstance(target, type), "Class-level Event targets must be classes."
+ assert isinstance(target, type), \
+ "Class-level Event targets must be classes."
for cls in [target] + target.__subclasses__():
self._clslevel[cls].append(obj)
.. note:: :class:`PoolListener` is deprecated. Please
refer to :func:`event.listen` as well as
- :attr:`Pool.events`.
+ :attr:`.Pool.events`.
Usage::
"""Allows interception of statement execution by Connections.
.. note:: :class:`ConnectionProxy` is deprecated. Please
- refer to :func:`event.listen`.
+ refer to :func:`event.listen` as well as
+ :attr:`.Engine.events`.
Either or both of the ``execute()`` and ``cursor_execute()``
may be implemented to intercept compiled statement and
manager.close()
proxies.clear()
+class PoolEvents(event.Events):
+ """Available events for :class:`.Pool`.
+
+ The methods here define the name of an event as well
+ as the names of members that are passed to listener
+ functions. Note all members are passed by name.
+
+ e.g.::
+
+ from sqlalchemy import events
+
+ def my_on_checkout(dbapi_conn, connection_rec, connection_proxy):
+ "handle an on checkout event"
+
+ events.listen(my_on_checkout, 'on_checkout', Pool)
+
+ """
+
+ def on_connect(self, dbapi_connection, connection_record):
+ """Called once for each new DB-API connection or Pool's ``creator()``.
+
+ :param dbapi_con:
+ A newly connected raw DB-API connection (not a SQLAlchemy
+ ``Connection`` wrapper).
+
+ :param con_record:
+ The ``_ConnectionRecord`` that persistently manages the connection
+
+ """
+
+ def on_first_connect(self, dbapi_connection, connection_record):
+ """Called exactly once for the first DB-API connection.
+
+ :param dbapi_con:
+ A newly connected raw DB-API connection (not a SQLAlchemy
+ ``Connection`` wrapper).
+
+ :param con_record:
+ The ``_ConnectionRecord`` that persistently manages the connection
+
+ """
+
+ def on_checkout(self, dbapi_connection, connection_record, connection_proxy):
+ """Called when a connection is retrieved from the Pool.
+
+ :param dbapi_con:
+ A raw DB-API connection
+
+ :param con_record:
+ The ``_ConnectionRecord`` that persistently manages the connection
+
+ :param con_proxy:
+ The ``_ConnectionFairy`` which manages the connection for the span of
+ the current checkout.
+
+ If you raise an ``exc.DisconnectionError``, the current
+ connection will be disposed and a fresh connection retrieved.
+ Processing of all checkout listeners will abort and restart
+ using the new connection.
+ """
+
+ def on_checkin(self, dbapi_connection, connection_record):
+ """Called when a connection returns to the pool.
+
+ Note that the connection may be closed, and may be None if the
+ connection has been invalidated. ``checkin`` will not be called
+ for detached connections. (They do not return to the pool.)
+
+ :param dbapi_con:
+ A raw DB-API connection
+
+ :param con_record:
+ The ``_ConnectionRecord`` that persistently manages the connection
+
+ """
+
class Pool(log.Identified):
"""Abstract base class for connection pools."""
for l in listeners:
self.add_listener(l)
- class events(event.Events):
- """Available events for :class:`Pool`.
-
- The methods here define the name of an event as well
- as the names of members that are passed to listener
- functions. Note all members are passed by name.
-
- e.g.::
-
- from sqlalchemy import events
- events.listen(fn, 'on_checkout', Pool)
-
- """
-
- def on_connect(self, dbapi_connection, connection_record):
- """Called once for each new DB-API connection or Pool's ``creator()``.
-
- :param dbapi_con:
- A newly connected raw DB-API connection (not a SQLAlchemy
- ``Connection`` wrapper).
-
- :param con_record:
- The ``_ConnectionRecord`` that persistently manages the connection
-
- """
-
- def on_first_connect(self, dbapi_connection, connection_record):
- """Called exactly once for the first DB-API connection.
-
- :param dbapi_con:
- A newly connected raw DB-API connection (not a SQLAlchemy
- ``Connection`` wrapper).
-
- :param con_record:
- The ``_ConnectionRecord`` that persistently manages the connection
-
- """
-
- def on_checkout(self, dbapi_connection, connection_record, connection_proxy):
- """Called when a connection is retrieved from the Pool.
-
- :param dbapi_con:
- A raw DB-API connection
-
- :param con_record:
- The ``_ConnectionRecord`` that persistently manages the connection
-
- :param con_proxy:
- The ``_ConnectionFairy`` which manages the connection for the span of
- the current checkout.
-
- If you raise an ``exc.DisconnectionError``, the current
- connection will be disposed and a fresh connection retrieved.
- Processing of all checkout listeners will abort and restart
- using the new connection.
- """
-
- def on_checkin(self, dbapi_connection, connection_record):
- """Called when a connection returns to the pool.
-
- Note that the connection may be closed, and may be None if the
- connection has been invalidated. ``checkin`` will not be called
- for detached connections. (They do not return to the pool.)
-
- :param dbapi_con:
- A raw DB-API connection
-
- :param con_record:
- The ``_ConnectionRecord`` that persistently manages the connection
-
- """
- events = event.dispatcher(events)
+ events = event.dispatcher(PoolEvents)
- @util.deprecated("Pool.add_listener() is deprecated. Use event.listen()")
+ @util.deprecated(":meth:`.Pool.add_listener` is deprecated. Use :func:`.event.listen`")
def add_listener(self, listener):
- """Add a ``PoolListener``-like object to this pool.
+ """Add a :class:`.PoolListener`-like object to this pool.
``listener`` may be an object that implements some or all of
PoolListener, or a dictionary of callables containing implementations
assert_listeners(p, 1, 1, 1, 1)
p.add_listener(i_connect)
- assert_listeners(p, 2, 2, 1, 1)
+ assert_listeners(p, 2, 1, 1, 1)
p.add_listener(i_checkout)
- assert_listeners(p, 3, 2, 2, 1)
+ assert_listeners(p, 3, 1, 1, 1)
p.add_listener(i_checkin)
- assert_listeners(p, 4, 2, 2, 2)
+ assert_listeners(p, 4, 1, 1, 1)
del p
p = _pool(listeners=[i_all])
assert counts == [1, 2, 1]
p.add_listener(i_checkin)
c.close()
- assert counts == [1, 2, 3]
+ assert counts == [1, 2, 2]
def test_listener_after_oninit(self):
"""Test that listeners are called after OnInit is removed"""
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
