From: Federico Caselli <cfederico87@gmail.com>
Date: Thu, 30 Nov 2023 21:40:43 +0000 (+0100)
Subject: Improve session after_begin even documentation
X-Git-Tag: rel_2_0_24~17
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=933a3eca9600d3654f459274aa35df7aec77c83d;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Improve session after_begin even documentation

Change-Id: Ie2a1e6bdf5960208921dc76e372fe51d3b280f1a
References: #10687
(cherry picked from commit 842b3ebb4b9e40ce3f6aa4257bd5e585c42e51d2)
---

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index e7e3e32a7f..1a54dfd49a 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -2035,7 +2035,14 @@ class SessionEvents(event.Events[Session]):
         transaction: SessionTransaction,
         connection: Connection,
     ) -> None:
-        """Execute after a transaction is begun on a connection
+        """Execute after a transaction is begun on a connection.
+
+        .. note:: This event is called within the process of the
+          :class:`_orm.Session` modifying its own internal state.
+          To invoke SQL operations within this hook, use the
+          :class:`_engine.Connection` provided to the event;
+          do not run SQL operations using the :class:`_orm.Session`
+          directly.
 
         :param session: The target :class:`.Session`.
         :param transaction: The :class:`.SessionTransaction`.