docs: add template strings query documentation

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index 4dfaec271ba1632a4077c29a22fad6c29be82580..951a6202d6376a58a90e2fbdcf1592438aa2690b 100644 (file)
--- a/docs/api/connections.rst
+++ b/docs/api/connections.rst
@@ -143,8 +143,10 @@ The `!Connection` class
     .. automethod:: execute
 
         :param query: The query to execute.
-        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
+        :type query: `~typing.LiteralString`, `!bytes`, `sql.SQL`, `sql.Composed`,
+            or `~string.templatelib.Template`
         :param params: The parameters to pass to the query, if any.
+            Can't be specified if ``query`` is a `!Template`.
         :type params: Sequence or Mapping
         :param prepare: Force (`!True`) or disallow (`!False`) preparation of
             the query. By default (`!None`) prepare automatically. See

diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index 826b568f0c9b75aae5d8fed75743479f022892ba..c3e1ea3d08088d0ef056176f78a0fd3ff51fc2c4 100644 (file)
--- a/docs/api/cursors.rst
+++ b/docs/api/cursors.rst
@@ -62,8 +62,10 @@ The `!Cursor` class
     .. automethod:: execute
 
         :param query: The query to execute.
-        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
+        :type query: `~typing.LiteralString`, `!bytes`, `sql.SQL`, `sql.Composed`,
+            or `~string.templatelib.Template`
         :param params: The parameters to pass to the query, if any.
+            Can't be specified if ``query`` is a `!Template`.
         :type params: Sequence or Mapping
         :param prepare: Force (`!True`) or disallow (`!False`) preparation of
             the query. By default (`!None`) prepare automatically. See
@@ -89,7 +91,7 @@ The `!Cursor` class
     .. automethod:: executemany
 
         :param query: The query to execute
-        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
+        :type query: `~typing.LiteralString`, `!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
@@ -402,8 +404,10 @@ The `!ServerCursor` class
     .. automethod:: execute
 
         :param query: The query to execute.
-        :type query: `!str`, `!bytes`, `sql.SQL`, or `sql.Composed`
+        :type query: `~typing.LiteralString`, `!bytes`, `sql.SQL`, `sql.Composed`,
+            or `~string.templatelib.Template`
         :param params: The parameters to pass to the query, if any.
+            Can't be specified if ``query`` is a `!Template`.
         :type params: Sequence or Mapping
         :param binary: Specify whether the server should return data in binary
             format (`!True`) or in text format (`!False`). By default

diff --git a/docs/api/sql.rst b/docs/api/sql.rst
index 5e7000b269be7d3b954fbfdf6f228cc9425b0535..86e1a40e8b0a4fb1a1331ac93adc0dbedf13b85c 100644 (file)
--- a/docs/api/sql.rst
+++ b/docs/api/sql.rst
@@ -139,6 +139,11 @@ The `!sql` objects are in the following inheritance hierarchy:
 
     .. automethod:: join
 
+        .. versionchanged:: 3.3
+
+            Added support for `~string.templatelib.Template` sequences.
+            See :ref:`nested template strings <tstring-template-nested>`.
+
 
 .. autoclass:: Identifier
 

diff --git a/docs/basic/params.rst b/docs/basic/params.rst
index 0158337f4ca1a8b0f235100ae9f4c3eb69e85cd0..ff99de12935f00699da771f475d4069e18c2a657 100644 (file)
--- a/docs/basic/params.rst
+++ b/docs/basic/params.rst
@@ -8,6 +8,12 @@
 Passing parameters to SQL queries
 =================================
 
+.. note::
+
+   This way of passing queries has been the "classic" way for many years.
+   However, starting from Python 3.14, you might be interested in using the
+   more expressive :ref:`template string queries <template-strings>`.
+
 Most of the times, writing a program you will have to mix bits of SQL
 statements with values provided by the rest of the program:
 

diff --git a/docs/basic/tstrings.rst b/docs/basic/tstrings.rst
index b6496eabc2e8a128efd8409fe553f0f13b94f8a9..c2682d10eecf772389ade136ce1dfe1f4c1fe95c 100644 (file)
--- a/docs/basic/tstrings.rst
+++ b/docs/basic/tstrings.rst
@@ -10,18 +10,6 @@ Template string queries
 
 .. versionadded:: 3.3
 
-.. warning::
-
-    This is an experimental feature, still `under active development`__ and
-    only documented here for preview. Details may change before Psycopg 3.3
-    release.
-
-    .. __: https://github.com/psycopg/psycopg/pull/1054
-
-    Template strings are a Python language feature under active development
-    too, planned for release in Python 3.14. Template string queries are
-    currently tested in Python 3.14 beta 1.
-
 Psycopg can process queries expressed as `template strings`__ defined in
 :pep:`750` and implemented for the first time in Python 3.14.
 
@@ -149,7 +137,7 @@ be written as:
     ) -> list[User]:
         filters = []
         if ids is not None:
-            filters.append(t"u.id = any({list(ids)})")
+            filters.append(t"u.id = ANY({list(ids)})")
         if name_pattern is not None:
             filters.append(t"u.name ~* {name_pattern}")
         if group_id is not None: