docs: mention LiteralString and related changes in docs

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index b1858fb1dda8b2f21c55bcc12bc22d60cf2d8278..93ea5218dd3100e4d2db3e33d5bc52e387fe1681 100644 (file)
--- a/docs/api/connections.rst
+++ b/docs/api/connections.rst
@@ -143,7 +143,7 @@ The `!Connection` class
     .. automethod:: execute
 
         :param query: The query to execute.
-        :type query: `!str`, `!bytes`, or `sql.Composable`
+        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
         :param params: The parameters to pass to the query, if any.
         :type params: Sequence or Mapping
         :param prepare: Force (`!True`) or disallow (`!False`) preparation of

diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index a3be8b6037043bb09474d07617018a530efc0a31..f0f5df75682b88d76d4a8a0248fc99f67a0b45a5 100644 (file)
--- a/docs/api/cursors.rst
+++ b/docs/api/cursors.rst
@@ -61,7 +61,7 @@ The `!Cursor` class
     .. automethod:: execute
 
         :param query: The query to execute.
-        :type query: `!str`, `!bytes`, or `sql.Composable`
+        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
         :param params: The parameters to pass to the query, if any.
         :type params: Sequence or Mapping
         :param prepare: Force (`!True`) or disallow (`!False`) preparation of
@@ -77,10 +77,18 @@ The `!Cursor` class
         See :ref:`query-parameters` for all the details about executing
         queries.
 
+        .. versionchanged:: 3.1
+
+            The `query` argument must be a `~typing.StringLiteral`. If you
+            need to compose a query dynamically, please use `sql.SQL` and
+            related objects.
+
+            See :pep:`675` for details.
+
     .. automethod:: executemany
 
         :param query: The query to execute
-        :type query: `!str`, `!bytes`, or `sql.Composable`
+        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
         :param params_seq: The parameters to pass to the query
         :type params_seq: Sequence of Sequences or Mappings
         :param returning: If `!True`, fetch the results of the queries executed
@@ -109,7 +117,7 @@ The `!Cursor` class
     .. automethod:: copy
 
         :param statement: The copy operation to execute
-        :type statement: `!str`, `!bytes`, or `sql.Composable`
+        :type statement: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
         :param params: The parameters to pass to the statement, if any.
         :type params: Sequence or Mapping
 
@@ -261,7 +269,7 @@ The `!ClientCursor` class
     .. automethod:: mogrify
 
         :param query: The query to execute.
-        :type query: `!str`, `!bytes`, or `sql.Composable`
+        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
         :param params: The parameters to pass to the query, if any.
         :type params: Sequence or Mapping
 
@@ -315,7 +323,7 @@ The `!ServerCursor` class
     .. automethod:: execute
 
         :param query: The query to execute.
-        :type query: `!str`, `!bytes`, or `sql.Composable`
+        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
         :param params: The parameters to pass to the query, if any.
         :type params: Sequence or Mapping
         :param binary: Specify whether the server shoul return data in binary

diff --git a/docs/api/sql.rst b/docs/api/sql.rst
index 63906f8739e8b6628083e990383602be6d57f807..6959fee4dba87df92ec7f2c74a0fe9f236f21a16 100644 (file)
--- a/docs/api/sql.rst
+++ b/docs/api/sql.rst
@@ -114,6 +114,11 @@ The `!sql` objects are in the following inheritance hierarchy:
 
 .. autoclass:: SQL
 
+    .. versionchanged:: 3.1
+
+        The input object should be a `~typing.LiteralString`. See :pep:`675`
+        for details.
+
     .. automethod:: format
 
     .. automethod:: join

diff --git a/docs/basic/params.rst b/docs/basic/params.rst
index 5033e9a91d676424e09ff32efc31b099378d977a..27d80431013dc51b44a5d728058caa38553b1216 100644 (file)
--- a/docs/basic/params.rst
+++ b/docs/basic/params.rst
@@ -186,6 +186,21 @@ argument of the `Cursor.execute()` method::
     at :ref:`how Psycopg converts data types <types-adaptation>`.
 
 
+Using `LiteralString` in queries
+--------------------------------
+
+The `~Cursor.execute()` method and similar should only receive a literal
+string as input, according to :pep:`675`.
+
+If you need to compose a query dynamically you should use `sql.SQL` and
+similar methods.
+
+At the time of writing the feature is experimental and only checked by the
+Pyre_ checker.
+
+.. _Pyre: https://pyre-check.org/
+
+
 .. index::
     pair: Binary; Parameters
 

diff --git a/docs/news.rst b/docs/news.rst
index e5f75ef92134f735b9be2f40496142e8b11d39c1..c6d00304eb017d5226a12cbe31fa201313934386 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -28,6 +28,8 @@ Psycopg 3.1 (unreleased)
 - Add ``prepare_threshold`` parameter to `Connection` init (:ticket:`#200`).
 - Add ``cursor_factory`` parameter to `Connection` init.
 - Add `Error.pgconn` and `Error.pgresult` attributes (:ticket:`#242`).
+- Restrict queries to be `~typing.LiteralString` as per :pep:`675`
+  (:ticket:`#323`).
 - Add explicit type cast to values converted by `sql.Literal` (:ticket:`#205`).
 - Drop support for Python 3.6.