From 1116bce258f7c0d11b18622cecdbcdbfb9504f28 Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Tue, 15 Aug 2023 16:28:01 +0100
Subject: [PATCH] docs: improve docs about raw query cursors, add release note

---
 docs/advanced/cursors.rst | 12 +++++++-----
 docs/api/cursors.rst      | 40 ++++++++++++++++++++++++++++++---------
 docs/news.rst             |  2 ++
 3 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/docs/advanced/cursors.rst b/docs/advanced/cursors.rst
index f5e369ed0..7ec2e60b1 100644
--- a/docs/advanced/cursors.rst
+++ b/docs/advanced/cursors.rst
@@ -191,6 +191,7 @@ directly call the fetch methods, skipping the `~ServerCursor.execute()` call:
     for record in cur:  # or cur.fetchone(), cur.fetchmany()...
         # do something with record
 
+
 .. _raw-query-cursors:
 
 Raw Query Cursors
@@ -198,11 +199,12 @@ Raw Query Cursors
 
 .. versionadded:: 3.2
 
-Raw query cursors allow users to use PostgreSQL native placeholders ($1, $2,
-etc.) in their queries instead of the standard %s placeholder. This can be
-useful when it's desirable to pass the query unmodified to PostgreSQL and rely
-on PostgreSQL's placeholder functionality, such as when dealing with a very
-complex query containing %s inside strings, dollar-quoted strings or elsewhere.
+The `RawCursor` and `AsyncRawCursor` classes allow users to use PostgreSQL
+native placeholders (``$1``, ``$2``, etc.) in their queries instead of the
+standard ``%s`` placeholder. This can be useful when it's desirable to pass
+the query unmodified to PostgreSQL and rely on PostgreSQL's placeholder
+functionality, such as when dealing with a very complex query containing
+``%s`` inside strings, dollar-quoted strings or elsewhere.
 
 One important note is that raw query cursors only accept positional arguments
 in the form of a list or tuple. This means you cannot use named arguments
diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index 5d0f66a23..b6f51f17b 100644
--- a/docs/api/cursors.rst
+++ b/docs/api/cursors.rst
@@ -315,6 +315,20 @@ The `!Cursor` class
           is text or binary.
 
 
+The `!RawCursor` class
+----------------------
+
+.. seealso:: See :ref:`raw-query-cursors` for details.
+
+.. autoclass:: RawCursor
+
+    This `Cursor` subclass has the same interface of the parent class but
+    supports placeholders in PostgreSQL format (``$1``, ``$2``...) rather than
+    in Python format (``%s``). Only positional parameters are supported.
+
+    .. versionadded:: 3.2
+
+
 The `!ClientCursor` class
 -------------------------
 
@@ -445,8 +459,13 @@ The `!ServerCursor` class
         .. _MOVE: https://www.postgresql.org/docs/current/sql-fetch.html
 
 
-The `!AsyncCursor` class
-------------------------
+Async cursor classes
+--------------------
+
+Every `Cursor` class has an equivalent `!Async` version exposing the same
+semantic with an `!async` interface. The main interface is described in
+`AsyncCursor`.
+
 
 .. autoclass:: AsyncCursor
 
@@ -506,21 +525,24 @@ The `!AsyncCursor` class
         to iterate on the async cursor results.
 
 
-The `!AsyncClientCursor` class
-------------------------------
+
+.. autoclass:: AsyncRawCursor
+
+    This class is the `!async` equivalent of `RawCursor`. The differences 
+    w.r.t. the sync counterpart are the same described in `AsyncCursor`.
+
+    .. versionadded:: 3.2
+
 
 .. autoclass:: AsyncClientCursor
 
-    This class is the `!async` equivalent of the `ClientCursor`. The
-    difference are the same shown in `AsyncCursor`.
+    This class is the `!async` equivalent of `ClientCursor`. The differences
+    w.r.t. the sync counterpart are the same described in `AsyncCursor`.
 
     .. versionadded:: 3.1
 
 
 
-The `!AsyncServerCursor` class
-------------------------------
-
 .. autoclass:: AsyncServerCursor
 
     This class implements a DBAPI-inspired interface as the `AsyncCursor`
diff --git a/docs/news.rst b/docs/news.rst
index b306f6e39..153305ef6 100644
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -15,6 +15,8 @@ Psycopg 3.2 (unreleased)
 
 - Add support for integer, floating point, boolean `NumPy scalar types`__
   (:ticket:`#332`).
+- Add :ref:`raw-query-cursors` to execute queries using placeholders in
+  PostgreSQL format (`$1`, `$2`...) (:ticket:`#560`).
 - Add support for libpq functions to close prepared statements and portals
   introduced in libpq v17 (:ticket:`#603`).
 - Disable receiving more than one result on the same cursor in pipeline mode,
-- 
2.47.2