diff options
Diffstat (limited to 'lib/sqlalchemy/engine/events.py')
| -rw-r--r-- | lib/sqlalchemy/engine/events.py | 40 |
1 files changed, 23 insertions, 17 deletions
diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py index 46459cf73..65b73002c 100644 --- a/lib/sqlalchemy/engine/events.py +++ b/lib/sqlalchemy/engine/events.py @@ -61,7 +61,7 @@ class ConnectionEvents(event.Events): statement = statement + " -- some comment" return statement, parameters - .. note:: :class:`.ConnectionEvents` can be established on any + .. note:: :class:`_events.ConnectionEvents` can be established on any combination of :class:`_engine.Engine`, :class:`_engine.Connection`, as well as instances of each of those classes. Events across all @@ -183,7 +183,8 @@ class ConnectionEvents(event.Events): :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. - :param result: :class:`.ResultProxy` generated by the execution. + :param result: :class:`_engine.ResultProxy` generated by the execution + . """ @@ -208,7 +209,7 @@ class ConnectionEvents(event.Events): # do something with statement, parameters return statement, parameters - See the example at :class:`.ConnectionEvents`. + See the example at :class:`_events.ConnectionEvents`. :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object @@ -237,7 +238,7 @@ class ConnectionEvents(event.Events): :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object. Will have results pending if the statement was a SELECT, but these should not be consumed - as they will be needed by the :class:`.ResultProxy`. + as they will be needed by the :class:`_engine.ResultProxy`. :param statement: string SQL statement, as passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being passed to the ``execute()`` or ``executemany()`` method of the @@ -317,7 +318,8 @@ class ConnectionEvents(event.Events): "failed" in str(context.original_exception): raise MySpecialException("failed operation") - .. warning:: Because the :meth:`.ConnectionEvents.handle_error` + .. warning:: Because the + :meth:`_events.ConnectionEvents.handle_error` event specifically provides for exceptions to be re-thrown as the ultimate exception raised by the failed statement, **stack traces will be misleading** if the user-defined event @@ -358,7 +360,7 @@ class ConnectionEvents(event.Events): class for details on all available members. .. versionadded:: 0.9.7 Added the - :meth:`.ConnectionEvents.handle_error` hook. + :meth:`_events.ConnectionEvents.handle_error` hook. .. versionchanged:: 1.1 The :meth:`.handle_error` event will now receive all exceptions that inherit from ``BaseException``, @@ -429,7 +431,7 @@ class ConnectionEvents(event.Events): .. seealso:: :ref:`pool_disconnects_pessimistic` - illustrates how to use - :meth:`.ConnectionEvents.engine_connect` + :meth:`_events.ConnectionEvents.engine_connect` to transparently ensure pooled connections are connected to the database. @@ -437,7 +439,8 @@ class ConnectionEvents(event.Events): the lower-level pool checkout event for an individual DBAPI connection - :meth:`.ConnectionEvents.set_connection_execution_options` - a copy + :meth:`_events.ConnectionEvents.set_connection_execution_options` + - a copy of a :class:`_engine.Connection` is also made when the :meth:`_engine.Connection.execution_options` method is called. @@ -456,7 +459,7 @@ class ConnectionEvents(event.Events): :class:`_engine.Connection` is produced which is inheriting execution options from its parent :class:`_engine.Engine`; to intercept this condition, use the - :meth:`.ConnectionEvents.engine_connect` event. + :meth:`_events.ConnectionEvents.engine_connect` event. :param conn: The newly copied :class:`_engine.Connection` object @@ -467,7 +470,8 @@ class ConnectionEvents(event.Events): .. seealso:: - :meth:`.ConnectionEvents.set_engine_execution_options` - event + :meth:`_events.ConnectionEvents.set_engine_execution_options` + - event which is called when :meth:`_engine.Engine.execution_options` is called. @@ -483,7 +487,8 @@ class ConnectionEvents(event.Events): That new :class:`_engine.Engine` is passed here. A particular application of this - method is to add a :meth:`.ConnectionEvents.engine_connect` event + method is to add a :meth:`_events.ConnectionEvents.engine_connect` + event handler to the given :class:`_engine.Engine` which will perform some per- :class:`_engine.Connection` task specific to these execution options. @@ -497,7 +502,8 @@ class ConnectionEvents(event.Events): .. seealso:: - :meth:`.ConnectionEvents.set_connection_execution_options` - event + :meth:`_events.ConnectionEvents.set_connection_execution_options` + - event which is called when :meth:`_engine.Connection.execution_options` is called. @@ -636,17 +642,17 @@ class DialectEvents(event.Events): These hooks are not for general use and are only for those situations where intricate re-statement of DBAPI mechanics must be injected onto an existing dialect. For general-use statement-interception events, - please use the :class:`.ConnectionEvents` interface. + please use the :class:`_events.ConnectionEvents` interface. .. seealso:: - :meth:`.ConnectionEvents.before_cursor_execute` + :meth:`_events.ConnectionEvents.before_cursor_execute` - :meth:`.ConnectionEvents.before_execute` + :meth:`_events.ConnectionEvents.before_execute` - :meth:`.ConnectionEvents.after_cursor_execute` + :meth:`_events.ConnectionEvents.after_cursor_execute` - :meth:`.ConnectionEvents.after_execute` + :meth:`_events.ConnectionEvents.after_execute` .. versionadded:: 0.9.4 |