Add standalone orm.close_all method and deprecate SessionMaker.close_all

Added a new function :func:`.close_all_sessions` which takes
over the task of the :meth:`.Session.close_all` method, which
is now deprecated as this is confusing as a classmethod.
Pull request courtesy Augustin Trancart.

Fixes: #4412

Closes: #4438
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/4438
Pull-request-sha: 7833d12a9898c82d50716427144bf3276c22ab3f

Change-Id: Ib35eaa520ae886f3f8f550f9712fc3b139e00b60

1 files changed, 25 insertions, 2 deletions

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index fbc268e01..360e73466 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -59,11 +59,16 @@ class _SessionClassMethods(object):
     """Class-level methods for :class:`.Session`, :class:`.sessionmaker`."""
 
     @classmethod
+    @util.deprecated(
+        "1.3",
+        "The :meth:`.Session.close_all` method is deprecated and will be "
+        "removed in a future release.  Please refer to "
+        ":func:`.session.close_all_sessions`.",
+    )
     def close_all(cls):
         """Close *all* sessions in memory."""
 
-        for sess in _sessions.values():
-            sess.close()
+        close_all_sessions()
 
     @classmethod
     @util.dependencies("sqlalchemy.orm.util")
@@ -3204,6 +3209,24 @@ class sessionmaker(_SessionClassMethods):
         )
 
 
+def close_all_sessions():
+    """Close all sessions in memory.
+
+    This function consults a global registry of all :class:`.Session` objects
+    and calls :meth:`.Session.close` on them, which resets them to a clean
+    state.
+
+    This function is not for general use but may be useful for test suites
+    within the teardown scheme.
+
+    .. versionadded:: 1.3
+
+    """
+
+    for sess in _sessions.values():
+        sess.close()
+
+
 def make_transient(instance):
     """Alter the state of the given instance so that it is :term:`transient`.