docs: improvement to the Cursor docs

diff --git a/docs/advanced/cursors.rst b/docs/advanced/cursors.rst
index 7ec2e60b134794ac3f418b6b323eff6c38ba4adc..8ece1e7e8fc571e9e7aa1aad34982ba182f432d8 100644 (file)
--- a/docs/advanced/cursors.rst
+++ b/docs/advanced/cursors.rst
@@ -8,9 +8,45 @@
 Cursor types
 ============
 
-Psycopg can manage kinds of "cursors" which differ in where the state of a
-query being processed is stored: :ref:`client-side-cursors` and
-:ref:`server-side-cursors`.
+Cursors are objects used to send commands to a PostgreSQL connection and to
+manage the results returned by it. They are normally created by the
+connection's `~Connection.cursor()` method.
+
+Psycopg can manage different kinds of "cursors", the objects used to send
+queries and retrieve results from the server. They differ from each other in
+aspects such as:
+
+- Are the parameters bound on the client or on the server?
+  :ref:`server-side-binding` can offer better performance (for instance
+  allowing to use prepared statements) and reduced memory footprint, but may
+  require stricter query definition and certain queries that work in
+  `!psycopg2` might need to be adapted.
+
+- Is the query result stored on the client or on the server? Server-side
+  cursors allow partial retrieval of large datasets, but they might offer less
+  performance in everyday usage.
+
+- Are queries manipulated by Python (to handle placeholders in ``%s`` and
+  ``%(name)s`` Python-style) or sent as they are to the PostgreSQL server
+  (which only supports ``$1``, ``$2`` parameters)?
+
+Psycopg exposes the following classes to implement the different strategies.
+All the classes are exposed by the main `!psycopg` package. Every class has
+also an `!Async`\ -prefixed counterparts, designed to be used in conjunction
+with `AsyncConnection` in `asyncio` programs.
+
+================= =========== =========== ==================== ==================================
+Class             Binding     Storage     Placeholders         See also
+================= =========== =========== ==================== ==================================
+`Cursor`          server-side client-side ``%s``, ``%(name)s`` :ref:`client-side-cursors`
+`ClientCursor`    cient-side  client-side ``%s``, ``%(name)s`` :ref:`client-side-binding-cursors`
+`ServerCursor`    server-side server-side ``%s``, ``%(name)s`` :ref:`server-side-cursors`
+`RawCursor`       server-side client-side ``$1``               :ref:`raw-query-cursors`
+================= =========== =========== ==================== ==================================
+
+If not specified by a `~Connection.cursor_factory`, `~Connection.cursor()`
+will usually produce `Cursor` objects.
+
 
 .. index::
     double: Cursor; Client-side
@@ -194,8 +230,8 @@ directly call the fetch methods, skipping the `~ServerCursor.execute()` call:
 
 .. _raw-query-cursors:
 
-Raw Query Cursors
-------------------
+Raw query cursors
+-----------------
 
 .. versionadded:: 3.2
 

diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index b6f51f17be31f3c7e8902e071c654f75f1c4fa5d..9abb3f989c3c19aa447f7b2cea58902f53ae2248 100644 (file)
--- a/docs/api/cursors.rst
+++ b/docs/api/cursors.rst
@@ -11,11 +11,12 @@ Using the `!name` parameter on `!cursor()` will create a `ServerCursor` or
 `AsyncServerCursor`, which can be used to retrieve partial results from a
 database.
 
-A `Connection` can create several cursors, but only one at time can perform
-operations, so they are not the best way to achieve parallelism (you may want
-to operate with several connections instead). All the cursors on the same
-connection have a view of the same session, so they can see each other's
-uncommitted data.
+Other cursor classes can be created by directly instantiating them, or can be
+set as `Connection.cursor_factory` to require them on `!cursor()` call.
+
+This page describe the details of the `!Cursor` class interface. Please refer
+to :ref:`cursor-types` for general information about the different types of
+cursors available in Psycopg.
 
 
 The `!Cursor` class