alleviate transaction confusion which may occur from reading just the "commit" doc

diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst
index 359f1a6c1d9409240896e5ab506cc3d31a59bddb..74c4a9b3f2f22bddea8fb7ceb5f4bf836d44ac40 100644 (file)
--- a/doc/build/orm/session.rst
+++ b/doc/build/orm/session.rst
@@ -636,10 +636,18 @@ transaction. It always issues :func:`~sqlalchemy.orm.session.Session.flush`
 beforehand to flush any remaining state to the database; this is independent
 of the "autoflush" setting. If no transaction is present, it raises an error.
 Note that the default behavior of the :class:`~sqlalchemy.orm.session.Session`
-is that a transaction is always present; this behavior can be disabled by
+is that a "transaction" is always present; this behavior can be disabled by
 setting ``autocommit=True``. In autocommit mode, a transaction can be
 initiated by calling the :func:`~sqlalchemy.orm.session.Session.begin` method.
 
+.. note:: The term "transaction" here refers to a transactional
+   construct within the :class:`.Session` itself which may be
+   maintaining zero or more actual database (DBAPI) transactions.  An individual
+   DBAPI connection begins participation in the "transaction" as it is first
+   used to execute a SQL statement, then remains present until the session-level
+   "transaction" is completed.  See :ref:`unitofwork_transaction` for 
+   further detail.
+
 Another behavior of :func:`~sqlalchemy.orm.session.Session.commit` is that by
 default it expires the state of all instances present after the commit is
 complete. This is so that when the instances are next accessed, either through