From 1f80e0bc14d58e857a4428e8bfe442ad890826a2 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 | 21 +++++---------------- docs/news.rst | 1 + 6 files changed, 27 insertions(+), 20 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 e63a98e18..ec7c8249f 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 @@ -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 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..1767daf18 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. @@ -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 `. - ``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 eea171517..9b20c9e92 100644 --- 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 ` (: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 -- 2.47.3