From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 9 May 2023 14:54:10 +0000 (-0400)
Subject: update errors page for greenlet error
X-Git-Tag: rel_2_0_13~9
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ddd25a03743543ed9a7f0a9516d3bfa2528b9fce;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

update errors page for greenlet error

the language here is adjusted to accommodate for newer
patterns with lazy loading and asyncio, most prominently
``AsyncAtrs``.

Change-Id: I9b2b9329158193f803c55c7e36dae16377e6c8e1
---

diff --git a/doc/build/errors.rst b/doc/build/errors.rst
index ea76a99140..2f2bfa91f4 100644
--- a/doc/build/errors.rst
+++ b/doc/build/errors.rst
@@ -1282,7 +1282,6 @@ the ``prebuffer_rows`` execution option may be used as follows::
 
     # context manager creates new Session
     with Session(engine) as session_obj:
-
         # result internally pre-fetches all objects
         result = sess.execute(
             select(User).where(User.id == 7), execution_options={"prebuffer_rows": True}
@@ -1364,7 +1363,6 @@ dataclass, such as in the example below::
 
 
     class Mixin:
-
         create_user: Mapped[int] = mapped_column()
         update_user: Mapped[Optional[int]] = mapped_column(default=None, init=False)
 
@@ -1400,7 +1398,6 @@ The fix is to add :class:`_orm.MappedAsDataclass` to the signature of
 ``Mixin`` as well::
 
     class Mixin(MappedAsDataclass):
-
         create_user: Mapped[int] = mapped_column()
         update_user: Mapped[Optional[int]] = mapped_column(default=None, init=False)
 
@@ -1500,14 +1497,17 @@ MissingGreenlet
 
 A call to the async :term:`DBAPI` was initiated outside the greenlet spawn
 context usually setup by the SQLAlchemy AsyncIO proxy classes. Usually this
-error happens when an IO was attempted in an unexpected place, without using
-the provided async api. When using the ORM this may be due to a lazy loading
-attempt, which is unsupported when using SQLAlchemy with AsyncIO dialects.
+error happens when an IO was attempted in an unexpected place, using a
+calling pattern that does not directly provide for use of the ``await`` keyword.
+When using the ORM this is nearly always due to the use of :term:`lazy loading`,
+which is not directly supported under asyncio without additional steps
+and/or alternate loader patterns in order to use successfully.
 
 .. seealso::
 
     :ref:`asyncio_orm_avoid_lazyloads` - covers most ORM scenarios where
-    this problem can occur and how to mitigate.
+    this problem can occur and how to mitigate, including specific patterns
+    to use with lazy load scenarios.
 
 .. _error_xd3s: