- rework the entire approach to #3076. As we need to catch all exceptions

in all cases unconditionally, the number of use cases that go beyond what
dbapi_error() is expecting has gone too far for an 0.9 release.
Additionally, the number of things we'd like to track is really a lot
more than the five arguments here, and ExecutionContext is really not
suitable as totally public API for this.   So restore dbapi_error
to its old version, deprecate, and build out handle_error instead.
This is a lot more extensible and doesn't get in the way of anything
compatibility-wise.

3 files changed, 6 insertions, 41 deletions

diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst
index d3bce5cbe..0dca50688 100644
--- a/doc/build/changelog/changelog_09.rst
+++ b/doc/build/changelog/changelog_09.rst
@@ -19,20 +19,9 @@
         :tickets: 3076
         :versions: 1.0.0
 
-        The mechanics of the :meth:`.ConnectionEvents.dbapi_error` handler
-        have been enhanced such that the function handler is now capable
-        of raising or returning a new exception object, which will replace
-        the exception normally being thrown by SQLAlchemy.
-
-    .. change::
-        :tags: feature, engine
-        :versions: 1.0.0
-
-        Added new attributes :attr:`.ExecutionContext.exception` and
-        :attr:`.ExecutionContext.is_disconnect` which are meaningful within
-        the :meth:`.ConnectionEvents.dbapi_error` handler to see both the
-        original DBAPI error as well as whether or not it represents
-        a disconnect.
+        Added new event :meth:`.ConnectionEvents.handle_error`, a more
+        fully featured and comprehensive replacement for
+        :meth:`.ConnectionEvents.dbapi_error`.
 
     .. change::
         :tags: bug, orm
diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst
index b9c45642c..06fccd1dd 100644
--- a/doc/build/changelog/migration_10.rst
+++ b/doc/build/changelog/migration_10.rst
@@ -133,33 +133,6 @@ than the integer value.
 
 .. _feature_3076:
 
-DBAPI Exceptions may be re-stated using events
-----------------------------------------------
-
-.. note::
-
-	this feature is also back-ported to SQLAlchemy 0.9.7.
-
-The :meth:`.ConnectionEvents.dbapi_error` handler may now be used to re-state
-the exception raised as an alternate, user-defined exception::
-
-    @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):
-            raise MySpecialException("failed operation")
-
-The handler supports both raising an exception immediately, as well
-as being able to return the new exception such that the chain of event handling
-will continue, the next event handler receiving the new exception as
-its argument.
-
-:ticket:`3076`
-
-.. seealso::
-
-	:meth:`.ConnectionEvents.dbapi_error`
-
 Behavioral Improvements
 =======================
 
diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index ca584f012..248309a2e 100644
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -568,6 +568,9 @@ Connection / Engine API
 .. autoclass:: Engine
    :members:
 
+.. autoclass:: sqlalchemy.engine.ExceptionContext
+   :members:
+
 .. autoclass:: NestedTransaction
     :members: