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

3 files changed, 28 insertions, 4 deletions

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 5c286a71b..1666104d9 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -40,6 +40,7 @@ from .relationships import foreign  # noqa
 from .relationships import RelationshipProperty  # noqa
 from .relationships import remote  # noqa
 from .scoping import scoped_session  # noqa
+from .session import close_all_sessions  # noqa
 from .session import make_transient  # noqa
 from .session import make_transient_to_detached  # noqa
 from .session import object_session  # noqa
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`.
 
diff --git a/lib/sqlalchemy/testing/fixtures.py b/lib/sqlalchemy/testing/fixtures.py
index 64d9328d7..953b229f2 100644
--- a/lib/sqlalchemy/testing/fixtures.py
+++ b/lib/sqlalchemy/testing/fixtures.py
@@ -246,7 +246,7 @@ class RemovesEvents(object):
 class _ORMTest(object):
     @classmethod
     def teardown_class(cls):
-        sa.orm.session.Session.close_all()
+        sa.orm.session.close_all_sessions()
         sa.orm.clear_mappers()
 
 
@@ -287,7 +287,7 @@ class MappedTest(_ORMTest, TablesTest, assertions.AssertsExecutionResults):
         self._setup_each_inserts()
 
     def teardown(self):
-        sa.orm.session.Session.close_all()
+        sa.orm.session.close_all_sessions()
         self._teardown_each_mappers()
         self._teardown_each_classes()
         self._teardown_each_tables()