From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 27 Jun 2022 21:55:57 +0000 (+0100)
Subject: docs: mention LiteralString and related changes in docs
X-Git-Tag: 3.1~53^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=00889f834c66ead7861d114f4924db3ced72e28e;p=thirdparty%2Fpsycopg.git

docs: mention LiteralString and related changes in docs
---

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index b1858fb1d..93ea5218d 100644
--- 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 a3be8b603..f0f5df756 100644
--- 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 63906f873..6959fee4d 100644
--- 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 5033e9a91..27d804310 100644
--- 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 e5f75ef92..c6d00304e 100644
--- 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.