Tidy up docs

Author: coleifer

docs/peewee/postgres.rst

@@ -74,16 +74,23 @@ you must use :class:`PostgresqlExtDatabase`.
 
 .. _psycopg2-vs-psycopg3:
 
-psycopg2 versus psycopg3
-------------------------
+psycopg2 vs psycopg3
+--------------------
 
-Peewee supports both drivers and uses psycopg2 when both are installed,
-unless ``prefer_psycopg3`` is given. Queries generated by peewee behave
-identically on either. The difference is in how hand-written SQL is bound:
-psycopg2 interpolates parameters into the query string on the client,
-psycopg3 sends the query and parameters separately and Postgres binds them.
-Server-side binding only accepts parameters in value positions of a single
-plannable statement:
+Peewee supports both drivers, and will use whichever is installed. If **both**
+psycopg2 and psycopg(3) are installed, Peewee defaults to psycopg2 unless
+``prefer_psycopg3=True`` is specified:
+
+.. code-block:: python
+
+   # If both psycopg2 and psycopg3 are installed, use psycopg3.
+   db = PostgresqlDatabase('peewee_test', prefer_psycopg3=True)
+
+Queries generated by peewee behave identically on either. The difference is in
+how hand-written SQL is bound: psycopg2 interpolates parameters into the query
+string on the client, while psycopg3 sends the query and parameters separately
+and Postgres binds them. psycopg3's server-side binding only accepts parameters
+in value positions within a single query:
 
 .. code-block:: python
 
@@ -103,8 +110,8 @@ passing psycopg's ``ClientCursor``:
 
    import psycopg
 
-   db = PostgresqlExtDatabase('my_app', prefer_psycopg3=True,
-                              cursor_factory=psycopg.ClientCursor)
+   db = PostgresqlDatabase('my_app', prefer_psycopg3=True,
+                           cursor_factory=psycopg.ClientCursor)
 
 In exchange, psycopg3 automatically promotes frequently-executed queries to
 server-side prepared statements, skipping repeated parse and plan overhead.
@@ -985,18 +992,17 @@ For more information, see the `Postgres full-text search docs <https://www.postg
 Server-Side Cursors
 -------------------
 
-For large result sets, server-side (named) cursors stream rows from the server
-rather than loading the entire result into memory. Rows are fetched
+For large result sets, server-side (or named) cursors stream rows from the
+server rather than loading the entire result into memory. Rows are fetched
 transparently from the server as you iterate. A regular cursor, by contrast,
-buffers the complete result set on the client at execute time, even when
-iterating with :meth:`~BaseQuery.iterator`.
+buffers the complete result set on the client at execute time.
 
 Refer to your driver documentation for details:
 
 * `psycopg2 server-side cursors <https://www.psycopg.org/docs/usage.html#server-side-cursors>`__
 * `psycopg3 server-side cursors <https://www.psycopg.org/psycopg3/docs/advanced/cursors.html#server-side-cursors>`__
 
-To use server-side (or named) cursors, you must be using :class:`PostgresqlExtDatabase`.
+To use server-side cursors, you must be using :class:`PostgresqlExtDatabase`.
 
 Wrap any SELECT query with :func:`ServerSide`:
 
@@ -1019,30 +1025,40 @@ Wrap any SELECT query with :func:`ServerSide`:
 
 Rows are fetched from the server in batches of ``array_size``, which defaults
 to the driver's ``itersize`` (2000 with psycopg2, 100 with psycopg3). For
-large scans specify ``array_size`` explicitly.
+large scans specify ``array_size`` explicitly:
+
+.. code-block:: python
 
-A named cursor is ordinarily bound to a transaction and is destroyed when the
-transaction ends. Declaring it ``WITH HOLD`` lets it outlive the transaction.
-The server pays for this at commit by copying the cursor's remaining rows
-into temporary storage, and later fetches read from that copy. Peewee
-connections autocommit, so a ``WITH HOLD`` cursor opened outside a
+   for page_view in ServerSide(large_query, array_size=1000):
+       # Do something interesting.
+       pass
+
+Ordinarily, a server-side cursor is bound to a transaction and is destroyed when the
+transaction ends. To use a server-side cursor outside a transaction, it must be
+declared ``WITH HOLD``, which has a couple consequences:
+
+* Server has to copy the cursor's rows into temporary storage upon commit, so
+  subsequent fetches read from the frozen copy.
+* Cursor must be exhausted or explicitly closed in order to release the held
+  resources.
+
+Peewee connections autocommit, so a ``WITH HOLD`` cursor opened outside a
 transaction is committed at once and materializes the entire result set
 before the first row arrives. Inside a transaction nothing is copied and
 rows stream on demand.
 
-Peewee declares ``WITH HOLD`` only when it has to. With psycopg3, a cursor
-opened inside a transaction is a plain named cursor. It streams, commit is
-instant, and the cursor ends with the transaction. Iterating after the
-transaction closes raises ``InvalidCursorName``. psycopg2 does not allow
-plain named cursors on autocommit connections, so peewee always declares
-``WITH HOLD`` there. Inside a transaction such a cursor streams all the same,
-but if it is still open when the transaction commits, the remaining rows are
-copied and the cursor survives.
-
-Iterate inside a transaction when you can. Use a cursor with no transaction
-when the iteration is too long to hold one open, and accept the up-front
-materialization. When the result fits in client memory, a regular cursor is
-simpler still.
+Peewee declares ``WITH HOLD`` only when it has to:
+
+* psycopg3: server-side cursors opened inside a transaction do not specify
+  ``WITH HOLD``. The cursor streams normally and the cursor ends with the
+  transaction. Iterating after the transaction closes will raise ``InvalidCursorName``.
+* psycopg2 does not allow server-side cursors on autocommit connections, so
+  peewee always declares ``WITH HOLD`` on psycopg2. Inside a transaction such a
+  cursor streams normally, but if it is still open when the transaction
+  commits, the remaining rows are copied and the cursor and resources survive.
+
+Use server-side cursors inside a transaction whenever possible. When the result
+fits in client memory, a regular (non-server-side) cursor is preferable.
 
 .. list-table::
    :header-rows: 1