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 e63a98e18b5b1f3180559b1ce186c82d65446729..ec7c8249f586665cb5cf09b8be28f6a607d2d7e5 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
@@ -421,8 +423,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..1767daf1841c64c53f16078fbd381bc7f3d65f17 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.
 
@@ -89,12 +77,12 @@ The supported specifiers for query composition are:
 
 - ``i``: the parameter is an identifier_, for example a table or column name.
   The parameter must be a string or a `sql.Identifier` instance.
-- ``l``: the parameter is a literal value, which will be composed to the
+- ``l``: the parameter is a literal value, which will be merged to the
   query on the client. This allows to parametrize statements that :ref:`don't
   support parametrization in PostgreSQL <server-side-binding>`.
 - ``q``: the parameter is a snippet of statement to be included verbatim in
-  the query. The parameter must be another template string or a `sql.SQL`
-  instance.
+  the query. The parameter must be another template string or a
+  `sql.SQL`\/\ `~sql.Composed` instance.
 
 .. _identifier: https://www.postgresql.org/docs/current/sql-syntax-lexical.html
                 #SQL-SYNTAX-IDENTIFIERS
@@ -149,7 +137,8 @@ be written as:
     ) -> list[User]:
         filters = []
         if ids is not None:
-            filters.append(t"u.id = any({list(ids)})")
+            ids = list(ids)
+            filters.append(t"u.id = ANY({ids})")
         if name_pattern is not None:
             filters.append(t"u.name ~* {name_pattern}")
         if group_id is not None:

diff --git a/docs/news.rst b/docs/news.rst
index eea1715174e25052623a983b13213b316fabae08..9b20c9e921f3280a62905ab22fe0423a47872c67 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -15,6 +15,7 @@ Psycopg 3.3.0 (unreleased)
 
 .. rubric:: New top-level features
 
+- Add :ref:`template strings queries <template-strings>` (:ticket:`#1054`).
 - Cursors are now iterators, not only iterables. This means you can call
   ``next(cur)`` to fetch the next row (:ticket:`#1064`).
 - Add `Cursor.results()` to iterate over the result sets of the queries