From de6f437f8218edcb55eef0a73758884486682536 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Tue, 18 Aug 2020 10:52:04 -0400 Subject: [PATCH] Clarify that session.close() is like reset This is a manual edit, not really a cherry-pick, but the below ref is where this is from. Fixes: #5517 Change-Id: I86809cf84de3ec19a279ae13f4e5e71336d8b359 (cherry picked from commit 7277c12e4d1bdc9647b9b306d89b5847d1c5a4d7) --- doc/build/orm/session_basics.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index df157c17c9..40715a7049 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -813,9 +813,15 @@ reset the state of the :class:`~sqlalchemy.orm.session.Session`. Closing ------- -The :meth:`~.Session.close` method issues a -:meth:`~.Session.expunge_all`, and :term:`releases` any -transactional/connection resources. When connections are returned to the -connection pool, transactional state is rolled back as well. +The :meth:`~.Session.close` method issues a :meth:`~.Session.expunge_all` which +removes all ORM-mapped objects from the session, and :term:`releases` any +transactional/connection resources from the :class:`_engine.Engine` object(s) +to which it is bound. When connections are returned to the connection pool, +transactional state is rolled back as well. + +When the :class:`_orm.Session` is closed, it is essentially in the +original state as when it was first constructed, and **may be used again**. +In this sense, the :meth:`_orm.Session.close` method is more like a "reset" +back to the clean state and not as much like a "database close" method. -- 2.39.5