From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 30 Jun 2022 19:00:08 +0000 (-0400)
Subject: more partition doc adjustments
X-Git-Tag: rel_1_4_40~41
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3e98a236008c0d4b7b83e70cfd1365c98dd42528;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

more partition doc adjustments

the partition story is not very good, this is a ton
of different options and they have to all be used
simultaenously for the common case.

Change-Id: I62963b7db1230a2670dda0ce812086f9265a3cb7
(cherry picked from commit aae1696a64509e54efd7d59a137c5ea6743363a7)
---

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index c683c7ee9d..b9ba6d9b39 100644
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -707,22 +707,23 @@ buffers of the given size, only fetching new rows when the buffer is empty::
         for row in result.yield_per(100):
             _process_row(row)
 
-The ``stream_results`` option is also available with the ORM.  When using the
-ORM, either the :meth:`_engine.Result.yield_per` or :meth:`_engine.Result.partitions`
-methods should be used to set the number of ORM rows to be buffered each time
-while yielding::
+The ``stream_results`` option is also available with the ORM. When using the
+ORM, the :meth:`_engine.Result.yield_per` method should be used to set the
+number of ORM rows to be buffered each time while yielding
+(:meth:`_engine.Result.partitions` uses the "yield per" value by default for
+partition size)::
 
     with orm.Session(engine) as session:
         result = session.execute(
             select(User).order_by(User_id).execution_options(stream_results=True),
         )
-        for partition in result.partitions(100):
+        for partition in result.yield_per(100).partitions():
             _process_rows(partition)
 
 
 .. note:: ORM result sets currently must make use of :meth:`_engine.Result.yield_per`
-   or :meth:`_engine.Result.partitions` in order to achieve streaming ORM results.
-   If either of these methods are not used to set the number of rows to
+   in order to achieve streaming ORM results.
+   If the method is not used to set the number of rows to
    fetch before yielding, the entire result is fetched before rows are yielded.
    This may change in a future release so that the automatic buffer size used
    by :class:`_engine.Connection` takes place for ORM results as well.
@@ -734,6 +735,12 @@ execution option::
     for row in session.query(User).yield_per(100):
         # process row
 
+.. seealso::
+
+    :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
+
+    :meth:`_engine.Result.partitions`
+
 
 .. _dbengine_implicit:
 
diff --git a/doc/build/orm/queryguide.rst b/doc/build/orm/queryguide.rst
index f3d4198398..261be27812 100644
--- a/doc/build/orm/queryguide.rst
+++ b/doc/build/orm/queryguide.rst
@@ -1018,14 +1018,17 @@ often useful to use with a result partitioning method such as
     ...
 
 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::
+with an ORM-enabled result set, which will have the similar effect at result
+fetching time as if the ``yield_per`` execution option were used, with the
+exception that ``stream_results`` option, described below, is not set
+automatically. 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():
+    {sql} >>> for partition in session.execute(
+    ...          stmt, execution_options={"stream_results": True}
+    ...       ).yield_per(10).partitions():
     ...     for row in partition:
     ...         print(row)
     SELECT user_account.id, user_account.name, user_account.fullname