From 71342488c387b64d69d070bbbaacb9df395d4baf Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Wed, 8 Sep 2021 23:19:20 +0200 Subject: [PATCH] docs: wordsmith --- docs/advanced/async.rst | 17 ++++++++--------- docs/advanced/cursors.rst | 32 ++++++++++++++++++-------------- 2 files changed, 26 insertions(+), 23 deletions(-) diff --git a/docs/advanced/async.rst b/docs/advanced/async.rst index 4f3e61a09..c49d6002c 100644 --- a/docs/advanced/async.rst +++ b/docs/advanced/async.rst @@ -4,8 +4,8 @@ .. _async: -Async operations -================ +Asynchronous operations +======================= Psycopg `~Connection` and `~Cursor` have counterparts `~AsyncConnection` and `~AsyncCursor` supporting an `asyncio` interface. @@ -63,8 +63,8 @@ For asynchronous connections it's *almost* what you'd expect, but not quite. Please note that `~Connection.connect()` and `~Connection.cursor()` *don't return a context*: they are both factory methods which return *an object which can be used as a context*. That's because there are several use -cases where it's useful to handle the object manually and `!close()` them when -required. +cases where it's useful to handle the objects manually and only `!close()` them +when required. As a consequence you cannot use `!async with connect()`: you have to do it in two steps instead, as in @@ -76,7 +76,7 @@ two steps instead, as in async with aconn.cursor() as cur: await cur.execute(...) -which can be condensed as: +which can be condensed into `!async with await`: .. code:: python @@ -86,10 +86,9 @@ which can be condensed as: ...but no less than that: you still need to do the double async thing. -The `AsyncConnection.cursor()` function is not marked as `!async` (it never -performs I/O), so you don't need an `!await` on it and you can use the normal -`async with` context manager. - +Note that the `AsyncConnection.cursor()` function is not an `!async` function +(it never performs I/O), so you don't need an `!await` on it; as a consequence +you can use the normal `async with` context manager. .. index:: diff --git a/docs/advanced/cursors.rst b/docs/advanced/cursors.rst index 9d9c18352..a77ec6478 100644 --- a/docs/advanced/cursors.rst +++ b/docs/advanced/cursors.rst @@ -58,13 +58,14 @@ is possible to transmit only them. The downside is that the server needs to keep track of the partially processed results, so it uses more memory and resources on the server. -Psycopg allows the use of server-side cursors using the classes -`ServerCursor` and `AsyncServerCursor`. They are usually created by passing -the *name* parameter to the `~Connection.cursor()` method (in `!psycopg2` they -are also called *named cursors*). The use of these classes is similar to their -client-side counterparts: their interface is the same, but behind the scene -they send commands to control the state of the cursor in the server (for -instance when fetching new records or when moving using `~Cursor.scroll()`). +Psycopg allows the use of server-side cursors using the classes `ServerCursor` +and `AsyncServerCursor`. They are usually created by passing the *name* +parameter to the `~Connection.cursor()` method (reason for which, in +`!psycopg2`, they are usually called *named cursors*). The use of these classes +is similar to their client-side counterparts: their interface is the same, but +behind the scene they send commands to control the state of the cursor on the +server (for instance when fetching new records or when moving using +`~Cursor.scroll()`). Using a server-side cursor it is possible to process datasets larger than what would fit in the client memory. However for small queries they are less @@ -88,10 +89,13 @@ result is needed. "Stealing" an existing cursor ----------------------------- -A Psycopg `ServerCursor` can be also used to consume a cursor that the -:sql:`DECLARE` generated by its `~ServerCursor.execute()` method can produce. +A Psycopg `ServerCursor` can be also used to consume a cursor which was +created in other ways than the :sql:`DECLARE` that `ServerCursor.execute()` +runs behind the scene. -For instance if you have a PL/pgSQL function creating a cursor: +For instance if you have a `PL/pgSQL function returning a cursor`__: + +.. __: https://www.postgresql.org/docs/current/plpgsql-cursors.html .. code:: postgres @@ -102,15 +106,15 @@ For instance if you have a PL/pgSQL function creating a cursor: END; $$ LANGUAGE plpgsql; -you can run a one-off command (e.g. using `Connection.execute()`) to call it -and create the server cursor: +you can run a one-off command in the same connection to call it (e.g. using +`Connection.execute()`) in order to create the cursor on the server: .. code:: python conn.execute("SELECT reffunc('curname')") -then create a server-side cursor with the same name and call directly the -fetch methods, omitting to call `~ServerCursor.execute()` before: +after which you can create a server-side cursor declared by the same name, and +call directly the fetch methods, skipping the `~ServerCursor.execute()` call: .. code:: python -- 2.47.3