From 62a48a906e4ce501f7d84e5f67b5cb84f01b905c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 12 Jan 2023 00:23:24 +0100 Subject: [PATCH 1/4] gh-100668: Clarify how sqlite3 maps parameters onto placeholders --- Doc/library/sqlite3.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 1708cd9d9580ad..4e8ad3f38c047d 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1943,12 +1943,13 @@ into the query by providing them as a :class:`tuple` of values to the second argument of the cursor's :meth:`~Cursor.execute` method. An SQL statement may use one of two kinds of placeholders: question marks (qmark style) or named placeholders (named style). For the qmark style, ``parameters`` must be a -:term:`sequence `. For the named style, it can be either a -:term:`sequence ` or :class:`dict` instance. The length of the -:term:`sequence ` must match the number of placeholders, or a -:exc:`ProgrammingError` is raised. If a :class:`dict` is given, it must contain -keys for all named parameters. Any extra items are ignored. Here's an example of -both styles: +:term:`sequence` whose length must match the number of placeholders, +or a :exc:`ProgrammingError` is raised. +For the named style, ``parameters`` should be a :class:`dict`, +or a :class:`!dict` subclass, +instance which must contain keys for all named parameters; +any extra items are ignored. +Here's an example of both styles: .. testcode:: @@ -1975,6 +1976,16 @@ both styles: [('C', 1972)] +.. note:: + + :pep:`249` numeric placeholders are not supported. + If used, they will be interpreted as named placeholders. + +Although **strongly discouraged**, for the named style, +``parameters`` can be supplied as a :term:`!sequence`. +This will result in the parameters being blindly bound to the placeholders +simply by index; parameter names will silently be ignored. + .. _sqlite3-adapters: From 46b0a1c1577ff0d03f9eaefe3b90791bcf610202 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 14 Jan 2023 21:23:01 +0100 Subject: [PATCH 2/4] Apply suggestions from CAM's review --- Doc/library/sqlite3.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4e8ad3f38c047d..4b716459fddd52 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1940,14 +1940,16 @@ close the single quote and inject ``OR TRUE`` to select all rows:: Instead, use the DB-API's parameter substitution. To insert a variable into a query string, use a placeholder in the string, and substitute the actual values into the query by providing them as a :class:`tuple` of values to the second -argument of the cursor's :meth:`~Cursor.execute` method. An SQL statement may -use one of two kinds of placeholders: question marks (qmark style) or named -placeholders (named style). For the qmark style, ``parameters`` must be a +argument of the cursor's :meth:`~Cursor.execute` method. + +An SQL statement may use one of two kinds of placeholders: +question marks (qmark style) or named placeholders (named style). +For the qmark style, *parameters* must be a :term:`sequence` whose length must match the number of placeholders, or a :exc:`ProgrammingError` is raised. -For the named style, ``parameters`` should be a :class:`dict`, -or a :class:`!dict` subclass, -instance which must contain keys for all named parameters; +For the named style, *parameters* should be +an instance of a :class:`dict` (or a subclass), +which must contain keys for all named parameters; any extra items are ignored. Here's an example of both styles: @@ -1982,7 +1984,7 @@ Here's an example of both styles: If used, they will be interpreted as named placeholders. Although **strongly discouraged**, for the named style, -``parameters`` can be supplied as a :term:`!sequence`. +*parameters* can be supplied as a :term:`!sequence`. This will result in the parameters being blindly bound to the placeholders simply by index; parameter names will silently be ignored. From 1f7c0515e1279fd94688f361a2ede568d80845fd Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 14 Jan 2023 21:24:16 +0100 Subject: [PATCH 3/4] Remove explanatory sentences, as this part is a how-to --- Doc/library/sqlite3.rst | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4b716459fddd52..22a69c9ce5e501 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1980,14 +1980,9 @@ Here's an example of both styles: .. note:: - :pep:`249` numeric placeholders are not supported. + :pep:`249` numeric placeholders are _not_ supported. If used, they will be interpreted as named placeholders. -Although **strongly discouraged**, for the named style, -*parameters* can be supplied as a :term:`!sequence`. -This will result in the parameters being blindly bound to the placeholders -simply by index; parameter names will silently be ignored. - .. _sqlite3-adapters: From 7ee56ba40e8930bc500a826b0799d9a2226c426a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sat, 14 Jan 2023 23:46:17 +0100 Subject: [PATCH 4/4] Fix formatting --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 22a69c9ce5e501..ba72b96c6741c4 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -1980,7 +1980,7 @@ Here's an example of both styles: .. note:: - :pep:`249` numeric placeholders are _not_ supported. + :pep:`249` numeric placeholders are *not* supported. If used, they will be interpreted as named placeholders.