From: Mike Bayer Date: Tue, 18 Aug 2020 14:52:04 +0000 (-0400) Subject: Clarify that session.close() is like reset X-Git-Tag: rel_1_3_20~40 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=de6f437f8218edcb55eef0a73758884486682536;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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) --- 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.