clarify that poolevents should be registered via engines

also clarify the role of engine.dispose()

references: #13097
Change-Id: I495863b58ffd05f4883f51ce2b3dcbd2bb2367b2

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 419ba6bf38a6a2819cfb92c55a22f8566426a60d..993eb2696844ba72f16ea8ecaae407bd175a9a13 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -3132,6 +3132,12 @@ class Engine(
         connections. The latter strategy is more appropriate for an initializer
         in a forked Python process.
 
+        Event listeners associated with the old pool via :class:`.PoolEvents`
+        are **transferred to the new pool**; this is to support the pattern
+        by which :class:`.PoolEvents` are set up in terms of the owning
+        :class:`.Engine` without the need to refer to the :class:`.Pool`
+        directly.
+
         :param close: if left at its default of ``True``, has the
          effect of fully closing all **currently checked in**
          database connections.  Connections that are still checked out
@@ -3157,6 +3163,8 @@ class Engine(
 
             :ref:`pooling_multiprocessing`
 
+            :meth:`.ConnectionEvents.engine_disposed`
+
         """
         if close:
             self.pool.dispose()

diff --git a/lib/sqlalchemy/pool/events.py b/lib/sqlalchemy/pool/events.py
index c7b7354dc5c31959f5b02e46b963f9b7579b5313..2fd02431621097accf7580b8723d44bfe7868afe 100644 (file)
--- a/lib/sqlalchemy/pool/events.py
+++ b/lib/sqlalchemy/pool/events.py
@@ -31,27 +31,30 @@ class PoolEvents(event.Events[Pool]):
     as the names of members that are passed to listener
     functions.
 
-    e.g.::
+    When using an :class:`.Engine` object created via :func:`_sa.create_engine`
+    (or indirectly via :func:`.create_async_engine`), :class:`.PoolEvents`
+    listeners are expected to be registered in terms of the :class:`.Engine`,
+    which will direct the listeners to the :class:`.Pool` contained within::
 
+        from sqlalchemy import create_engine
         from sqlalchemy import event
 
+        engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
+
 
+        @event.listens_for(engine, "checkout")
         def my_on_checkout(dbapi_conn, connection_rec, connection_proxy):
             "handle an on checkout event"
 
+    :class:`.PoolEvents` may also be registered with the :class:`_pool.Pool`
+    class, with the :class:`.Engine` class, as well as with instances of
+    :class:`_pool.Pool`.
 
-        event.listen(Pool, "checkout", my_on_checkout)
-
-    In addition to accepting the :class:`_pool.Pool` class and
-    :class:`_pool.Pool` instances, :class:`_events.PoolEvents` also accepts
-    :class:`_engine.Engine` objects and the :class:`_engine.Engine` class as
-    targets, which will be resolved to the ``.pool`` attribute of the
-    given engine or the :class:`_pool.Pool` class::
-
-        engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
+    .. tip::
 
-        # will associate with engine.pool
-        event.listen(engine, "checkout", my_on_checkout)
+        Registering :class:`.PoolEvents` with the :class:`.Engine`, if present,
+        is recommended since the :meth:`.Engine.dispose` method will carry
+        along event listeners from the old pool to the new pool.
 
     """  # noqa: E501