diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/sqlalchemy/engine/__init__.py | 1 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/base.py | 91 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/interfaces.py | 102 | ||||
| -rw-r--r-- | lib/sqlalchemy/events.py | 119 |
4 files changed, 244 insertions, 69 deletions
diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index fcb38b09c..9c6460858 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -54,6 +54,7 @@ from .interfaces import ( Connectable, Dialect, ExecutionContext, + ExceptionContext, # backwards compat Compiled, diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 67772f131..6da41927f 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -12,8 +12,8 @@ from __future__ import with_statement import sys from .. import exc, util, log, interfaces -from ..sql import expression, util as sql_util, schema, ddl -from .interfaces import Connectable, Compiled +from ..sql import util as sql_util +from .interfaces import Connectable, ExceptionContext from .util import _distill_params import contextlib @@ -1096,28 +1096,51 @@ class Connection(Connectable): should_wrap = isinstance(e, self.dialect.dbapi.Error) or \ (statement is not None and context is None) + if should_wrap: + sqlalchemy_exception = exc.DBAPIError.instance( + statement, + parameters, + e, + self.dialect.dbapi.Error, + connection_invalidated=self._is_disconnect) + else: + sqlalchemy_exception = None + newraise = None - if should_wrap and context: - if self._has_events or self.engine._has_events: - for fn in self.dispatch.dbapi_error: - try: - # handler returns an exception; - # call next handler in a chain - per_fn = fn(self, - cursor, - statement, - parameters, - context, - newraise - if newraise - is not None else e) - if per_fn is not None: - newraise = per_fn - except Exception as _raised: - # handler raises an exception - stop processing - newraise = _raised + if self._has_events or self.engine._has_events: + # legacy dbapi_error event + if should_wrap and context: + self.dispatch.dbapi_error(self, + cursor, + statement, + parameters, + context, + e) + + # new handle_error event + ctx = ExceptionContextImpl( + e, sqlalchemy_exception, self, cursor, statement, + parameters, context, self._is_disconnect) + + for fn in self.dispatch.handle_error: + try: + # handler returns an exception; + # call next handler in a chain + per_fn = fn(ctx) + if per_fn is not None: + ctx.chained_exception = newraise = per_fn + except Exception as _raised: + # handler raises an exception - stop processing + newraise = _raised + break + + if sqlalchemy_exception and \ + self._is_disconnect != ctx.is_disconnect: + sqlalchemy_exception.connection_invalidated = \ + self._is_disconnect = ctx.is_disconnect + if should_wrap and context: context.handle_dbapi_exception(e) if not self._is_disconnect: @@ -1129,16 +1152,11 @@ class Connection(Connectable): util.raise_from_cause(newraise, exc_info) elif should_wrap: util.raise_from_cause( - exc.DBAPIError.instance( - statement, - parameters, - e, - self.dialect.dbapi.Error, - connection_invalidated=self._is_disconnect), + sqlalchemy_exception, exc_info ) - - util.reraise(*exc_info) + else: + util.reraise(*exc_info) finally: del self._reentrant_error @@ -1224,6 +1242,21 @@ class Connection(Connectable): **kwargs).traverse_single(element) +class ExceptionContextImpl(ExceptionContext): + """Implement the :class:`.ExceptionContext` interface.""" + + def __init__(self, exception, sqlalchemy_exception, + connection, cursor, statement, parameters, + context, is_disconnect): + self.connection = connection + self.sqlalchemy_exception = sqlalchemy_exception + self.original_exception = exception + self.execution_context = context + self.statement = statement + self.parameters = parameters + self.is_disconnect = is_disconnect + + class Transaction(object): """Represent a database transaction in progress. diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 230d00fc0..1807e4283 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -882,3 +882,105 @@ class Connectable(object): def _execute_clauseelement(self, elem, multiparams=None, params=None): raise NotImplementedError() + +class ExceptionContext(object): + """Encapsulate information about an error condition in progress. + + This object exists solely to be passed to the + :meth:`.ConnectionEvents.handle_error` event, supporting an interface that + can be extended without backwards-incompatibility. + + .. versionadded:: 0.9.7 + + """ + + connection = None + """The :class:`.Connection` in use during the exception. + + This member is always present. + + """ + + cursor = None + """The DBAPI cursor object. + + May be None. + + """ + + statement = None + """String SQL statement that was emitted directly to the DBAPI. + + May be None. + + """ + + parameters = None + """Parameter collection that was emitted directly to the DBAPI. + + May be None. + + """ + + original_exception = None + """The exception object which was caught. + + This member is always present. + + """ + + sqlalchemy_exception = None + """The :class:`sqlalchemy.exc.StatementError` which wraps the original, + and will be raised if exception handling is not circumvented by the event. + + May be None, as not all exception types are wrapped by SQLAlchemy. + For DBAPI-level exceptions that subclass the dbapi's Error class, this + field will always be present. + + """ + + chained_exception = None + """The exception that was returned by the previous handler in the + exception chain, if any. + + If present, this exception will be the one ultimately raised by + SQLAlchemy unless a subsequent handler replaces it. + + May be None. + + """ + + execution_context = None + """The :class:`.ExecutionContext` corresponding to the execution + operation in progress. + + This is present for statement execution operations, but not for + operations such as transaction begin/end. It also is not present when + the exception was raised before the :class:`.ExecutionContext` + could be constructed. + + Note that the :attr:`.ExceptionContext.statement` and + :attr:`.ExceptionContext.parameters` members may represent a + different value than that of the :class:`.ExecutionContext`, + potentially in the case where a + :meth:`.ConnectionEvents.before_cursor_execute` event or similar + modified the statement/parameters to be sent. + + May be None. + + """ + + is_disconnect = None + """Represent whether the exception as occurred represents a "disconnect" + condition. + + This flag will always be True or False within the scope of the + :meth:`.ConnectionEvents.handle_error` handler. + + SQLAlchemy will defer to this flag in order to determine whether or not + the connection should be invalidated subsequently. That is, by + assigning to this flag, a "disconnect" event which then results in + a connection and pool invalidation can be invoked or prevented by + changing this flag. + + """ diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py index d3fe80b76..e4bc48615 100644 --- a/lib/sqlalchemy/events.py +++ b/lib/sqlalchemy/events.py @@ -494,10 +494,10 @@ class ConnectionEvents(event.Events): fn = wrap_before_cursor_execute elif retval and \ identifier not in ('before_execute', - 'before_cursor_execute', 'dbapi_error'): + 'before_cursor_execute', 'handle_error'): raise exc.ArgumentError( "Only the 'before_execute', " - "'before_cursor_execute' and 'dbapi_error' engine " + "'before_cursor_execute' and 'handle_error' engine " "event listeners accept the 'retval=True' " "argument.") event_key.with_wrapper(fn).base_listen() @@ -611,16 +611,72 @@ class ConnectionEvents(event.Events): This event is called with the DBAPI exception instance received from the DBAPI itself, *before* SQLAlchemy wraps the - exception with its own exception wrappers, and before any + exception with it's own exception wrappers, and before any other operations are performed on the DBAPI cursor; the existing transaction remains in effect as well as any state on the cursor. - The use cases supported by this hook include: + The use case here is to inject low-level exception handling + into an :class:`.Engine`, typically for logging and + debugging purposes. + + .. warning:: + + Code should **not** modify + any state or throw any exceptions here as this will + interfere with SQLAlchemy's cleanup and error handling + routines. For exception modification, please refer to the + new :meth:`.ConnectionEvents.handle_error` event. + + Subsequent to this hook, SQLAlchemy may attempt any + number of operations on the connection/cursor, including + closing the cursor, rolling back of the transaction in the + case of connectionless execution, and disposing of the entire + connection pool if a "disconnect" was detected. The + exception is then wrapped in a SQLAlchemy DBAPI exception + wrapper and re-thrown. + + :param conn: :class:`.Connection` object + :param cursor: DBAPI cursor object + :param statement: string SQL statement + :param parameters: Dictionary, tuple, or list of parameters being + passed to the ``execute()`` or ``executemany()`` method of the + DBAPI ``cursor``. In some cases may be ``None``. + :param context: :class:`.ExecutionContext` object in use. May + be ``None``. + :param exception: The **unwrapped** exception emitted directly from the + DBAPI. The class here is specific to the DBAPI module in use. + + .. deprecated:: 0.9.7 - replaced by + :meth:`.ConnectionEvents.handle_error` + + """ + + def handle_error(self, exception_context): + """Intercept all exceptions processed by the :class:`.Connection`. + + This includes all exceptions emitted by the DBAPI as well as + within SQLAlchemy's statement invocation process, including + encoding errors and other statement validation errors. Other areas + in which the event is invoked include transaction begin and end, + result row fetching, cursor creation. + + Note that :meth:`.handle_error` may support new kinds of exceptions + and new calling scenarios at *any time*. Code which uses this + event must expect new calling patterns to be present in minor + releases. + + To support the wide variety of members that correspond to an exception, + as well as to allow extensibility of the event without backwards + incompatibility, the sole argument received is an instance of + :class:`.ExceptionContext`. This object contains data members + representing detail about the exception. + + Use cases supported by this hook include: * read-only, low-level exception handling for logging and debugging purposes - * exception re-writing (0.9.7 and up only) + * exception re-writing The hook is called while the cursor from the failed operation (if any) is still open and accessible. Special cleanup operations @@ -630,10 +686,6 @@ class ConnectionEvents(event.Events): the scope of this hook; the rollback of the per-statement transaction also occurs after the hook is called. - When cleanup operations are complete, SQLAlchemy wraps the DBAPI-specific - exception in a SQLAlchemy-level wrapper mirroring the exception class, - and then propagates that new exception object. - The user-defined event handler has two options for replacing the SQLAlchemy-constructed exception into one that is user defined. It can either raise this new exception directly, in @@ -641,28 +693,26 @@ class ConnectionEvents(event.Events): exception will be raised, after appropriate cleanup as taken place:: - # 0.9.7 and up only !!! - @event.listens_for(Engine, "dbapi_error") - def handle_exception(conn, cursor, statement, parameters, context, exception): - if isinstance(exception, psycopg2.OperationalError) and \ - "failed" in str(exception): + @event.listens_for(Engine, "handle_error") + def handle_exception(context): + if isinstance(context.original_exception, + psycopg2.OperationalError) and \\ + "failed" in str(context.original_exception): raise MySpecialException("failed operation") Alternatively, a "chained" style of event handling can be used, by configuring the handler with the ``retval=True`` modifier and returning the new exception instance from the function. In this case, event handling will continue onto the - next handler, that handler receiving the new exception as its - argument:: - - # 0.9.7 and up only !!! - @event.listens_for(Engine, "dbapi_error", retval=True) - def handle_exception(conn, cursor, statement, parameters, context, exception): - if isinstance(exception, psycopg2.OperationalError) and \ - "failed" in str(exception): - return MySpecialException("failed operation") - else: - return None + next handler. The "chained" exception is available using + :attr:`.ExceptionContext.chained_exception`:: + + @event.listens_for(Engine, "handle_error", retval=True) + def handle_exception(context): + if context.chained_exception is not None and \\ + "special" in context.chained_exception.message: + return MySpecialException("failed", + cause=context.chained_exception) Handlers that return ``None`` may remain within this chain; the last non-``None`` return value is the one that continues to be @@ -676,22 +726,11 @@ class ConnectionEvents(event.Events): the ORM's feature of adding a detail hint about "autoflush" to exceptions raised within the autoflush process. - .. versionadded:: 0.9.7 Support for translation of DBAPI exceptions - into user-defined exceptions within the - :meth:`.ConnectionEvents.dbapi_error` event hook. - - :param conn: :class:`.Connection` object - :param cursor: DBAPI cursor object - :param statement: string SQL statement - :param parameters: Dictionary, tuple, or list of parameters being - passed to the ``execute()`` or ``executemany()`` method of the - DBAPI ``cursor``. In some cases may be ``None``. - :param context: :class:`.ExecutionContext` object in use. May - be ``None``. - :param exception: The **unwrapped** exception emitted directly from the - DBAPI. The class here is specific to the DBAPI module in use. + :param context: an :class:`.ExceptionContext` object. See this + class for details on all available members. - .. versionadded:: 0.7.7 + .. versionadded:: 0.9.7 Added the + :meth:`.ConnectionEvents.handle_error` hook. """ |