- Added new engine event :meth:`.ConnectionEvents.engine_disposed`.

Called after the :meth:`.Engine.dispose` method is called.

diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index 3a87a44a75d53d459404008ce6405b560597288d..c725d9e4adb3d365c03a8626ae111ef0cfa46cf6 100644 (file)
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -18,6 +18,12 @@
 .. changelog::
     :version: 1.0.5
 
+    .. change::
+        :tags: feature, engine
+
+        Added new engine event :meth:`.ConnectionEvents.engine_disposed`.
+        Called after the :meth:`.Engine.dispose` method is called.
+
     .. change::
         :tags: bug, postgresql, pypy
         :tickets: 3439

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 7ebe39bbf8f7e5e6a8124f49269b157943539afd..59754a436a700c3dca4de12c9c0060f906d7a2ac 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -1834,6 +1834,7 @@ class Engine(Connectable, log.Identified):
         """
         self.pool.dispose()
         self.pool = self.pool.recreate()
+        self.dispatch.engine_disposed(self)
 
     def _execute_default(self, default):
         with self.contextual_connect() as conn:

diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py
index b2d4b54a9df1ae352b0e99849a676e58acdf6f13..f439d554fb0ad4cb8356b4240c778891936b422b 100644 (file)
--- a/lib/sqlalchemy/events.py
+++ b/lib/sqlalchemy/events.py
@@ -882,6 +882,23 @@ class ConnectionEvents(event.Events):
 
         """
 
+    def engine_disposed(self, engine):
+        """Intercept when the :meth:`.Engine.dispose` method is called.
+
+        The :meth:`.Engine.dispose` method instructs the engine to
+        "dispose" of it's connection pool (e.g. :class:`.Pool`), and
+        replaces it with a new one.  Disposing of the old pool has the
+        effect that existing checked-in connections are closed.  The new
+        pool does not establish any new connections until it is first used.
+
+        This event can be used to indicate that resources related to the
+        :class:`.Engine` should also be cleaned up, keeping in mind that the
+        :class:`.Engine` can still be used for new requests in which case
+        it re-acquires connection resources.
+
+        .. versionadded:: 1.0.5
+
+        """
     def begin(self, conn):
         """Intercept begin() events.
 

diff --git a/test/engine/test_execute.py b/test/engine/test_execute.py
index 761ac102a0ed41fcac3215175d537ffb5f2132b3..c7b524335c41f4859684b4cbf075653e64b08bd5 100644 (file)
--- a/test/engine/test_execute.py
+++ b/test/engine/test_execute.py
@@ -483,6 +483,32 @@ class ExecuteTest(fixtures.TestBase):
 
         eq_(canary, ["l1", "l2", "l3", "l1", "l2"])
 
+    @testing.requires.ad_hoc_engines
+    def test_dispose_event(self):
+        canary = Mock()
+        eng = create_engine(testing.db.url)
+        event.listen(eng, "engine_disposed", canary)
+
+        conn = eng.connect()
+        conn.close()
+        eng.dispose()
+
+
+        conn = eng.connect()
+        conn.close()
+
+        eq_(
+            canary.mock_calls,
+            [call(eng)]
+        )
+
+        eng.dispose()
+
+        eq_(
+            canary.mock_calls,
+            [call(eng), call(eng)]
+        )
+
     @testing.requires.ad_hoc_engines
     def test_autocommit_option_no_issue_first_connect(self):
         eng = create_engine(testing.db.url)