From 9b4de735c8623cc32d3f498d76706b683c5f3baa Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Sun, 25 May 2025 23:22:13 +0100 Subject: [PATCH] docs: add template strings query documentation --- docs/api/connections.rst | 4 +++- docs/api/cursors.rst | 10 +++++++--- docs/api/sql.rst | 5 +++++ docs/basic/params.rst | 6 ++++++ docs/basic/tstrings.rst | 14 +------------- 5 files changed, 22 insertions(+), 17 deletions(-) diff --git a/docs/api/connections.rst b/docs/api/connections.rst index 4dfaec271..951a6202d 100644 --- 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 826b568f0..c3e1ea3d0 100644 --- 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 5e7000b26..86e1a40e8 100644 --- 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 `. + .. autoclass:: Identifier diff --git a/docs/basic/params.rst b/docs/basic/params.rst index 0158337f4..ff99de129 100644 --- 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 `. + 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 b6496eabc..c2682d10e 100644 --- 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: -- 2.39.5