From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 30 Jun 2022 17:33:30 +0000 (-0400)
Subject: add more cross-linking / notes for yield_per, partitions
X-Git-Tag: rel_1_4_40~42
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d04f013ee3fc7275f35bbc775427c02b719d1ed4;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add more cross-linking / notes for yield_per, partitions

Change-Id: I0f8db2532827c76a2751186638d22104230db843
references: #8198
(cherry picked from commit 59bafe0fbefe16269c72ac39e699e4127d49841f)
---

diff --git a/doc/build/orm/queryguide.rst b/doc/build/orm/queryguide.rst
index 012206ba7c..f3d4198398 100644
--- a/doc/build/orm/queryguide.rst
+++ b/doc/build/orm/queryguide.rst
@@ -1017,7 +1017,24 @@ often useful to use with a result partitioning method such as
     (User(id=1, name='spongebob', fullname='Spongebob Squarepants'),)
     ...
 
-The purpose of this method is when fetching very large result sets
+For expediency, the :meth:`_engine.Result.yield_per` method may also be used
+with an ORM-enabled result set, which will have the same effect at result
+fetching time as if the ``yield_per`` execution option were used. The
+:meth:`_engine.Result.partitions` method, if used, automatically uses the
+number sent to :meth:`_engine.Result.yield_per` as the number of rows in each
+partition::
+
+    >>> stmt = select(User)
+    {sql}>>> for partition in session.execute(stmt).yield_per(10).partitions():
+    ...     for row in partition:
+    ...         print(row)
+    SELECT user_account.id, user_account.name, user_account.fullname
+    FROM user_account
+    [...] (){stop}
+    (User(id=1, name='spongebob', fullname='Spongebob Squarepants'),)
+    ...
+
+The purpose of "yield per" is when fetching very large result sets
 (> 10K rows), to batch results in sub-collections and yield them
 out partially, so that the Python interpreter doesn't need to declare
 very large areas of memory which is both time consuming and leads
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index cb6906f036..6ca8f8c9d9 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -804,6 +804,12 @@ class Result(_WithKeys, ResultInternal):
         :param num: number of rows to fetch each time the buffer is refilled.
          If set to a value below 1, fetches all rows for the next buffer.
 
+        .. seealso::
+
+            :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
+
+            :meth:`_engine.Result.partitions`
+
         """
         self._yield_per = num
 
@@ -997,6 +1003,13 @@ class Result(_WithKeys, ResultInternal):
         results, if possible.   Not all drivers support this option and
         the option is silently ignored for those who do not.
 
+        When using the ORM, the :meth:`_engine.Result.partitions` method
+        is typically more effective from a memory perspective when it is
+        combined with use of the :meth:`_engine.Result.yield_per` method,
+        which instructs the ORM loading internals to only build a certain
+        amount of ORM objects from a result at a time before yielding
+        them out.
+
         .. versionadded:: 1.4
 
         :param size: indicate the maximum number of rows to be present
@@ -1007,6 +1020,13 @@ class Result(_WithKeys, ResultInternal):
 
         :return: iterator of lists
 
+        .. seealso::
+
+            :paramref:`.Connection.execution_options.stream_results`
+
+            :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
+
+
         """
 
         getter = self._manyrow_getter