From 18856268e7b1ea0e9b221cd113bd81ac080c4c4f Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sun, 9 Mar 2025 10:53:11 +0100 Subject: [PATCH 1/6] gh-131002: clarify how to enforce sqlite3 column types for generated fields --- Doc/library/sqlite3.rst | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4de09e14062d92..b90759304aa43d 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -290,9 +290,6 @@ Module functions :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES` to enable this. Column names takes precedence over declared types if both flags are set. - Types cannot be detected for generated fields (for example ``max(data)``), - even when the *detect_types* parameter is set; :class:`str` will be - returned instead. By default (``0``), type detection is disabled. :param isolation_level: @@ -436,21 +433,6 @@ Module constants old style (pre-Python 3.12) transaction control behaviour. See :ref:`sqlite3-transaction-control-isolation-level` for more information. -.. data:: PARSE_COLNAMES - - Pass this flag value to the *detect_types* parameter of - :func:`connect` to look up a converter function by - using the type name, parsed from the query column name, - as the converter dictionary key. - The type name must be wrapped in square brackets (``[]``). - - .. code-block:: sql - - SELECT p as "p [point]" FROM test; ! will look up converter "point" - - This flag may be combined with :const:`PARSE_DECLTYPES` using the ``|`` - (bitwise or) operator. - .. data:: PARSE_DECLTYPES Pass this flag value to the *detect_types* parameter of @@ -472,6 +454,25 @@ Module constants This flag may be combined with :const:`PARSE_COLNAMES` using the ``|`` (bitwise or) operator. + Generated fields (for example ``MAX(data)``) are returned as :class:`str`; + use :const:`!PARSE_COLNAMES` to enforce types for such queries. + +.. data:: PARSE_COLNAMES + + Pass this flag value to the *detect_types* parameter of + :func:`connect` to look up a converter function by + using the type name, parsed from the query column name, + as the converter dictionary key. + The query column name must be wrapped with double quotes (``"``), + and the type name must be wrapped in square brackets (``[]``), + + .. code-block:: sql + + SELECT MAX(p) as "p [point]" FROM test; ! will look up converter "point" + + This flag may be combined with :const:`PARSE_DECLTYPES` using the ``|`` + (bitwise or) operator. + .. data:: SQLITE_OK SQLITE_DENY SQLITE_IGNORE From 4d147445e309194d56e73d7c6f6b79d0a2a8b736 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sun, 9 Mar 2025 15:11:45 +0100 Subject: [PATCH 2/6] wrapped in --- 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 b90759304aa43d..eba4b8c625c548 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -463,7 +463,7 @@ Module constants :func:`connect` to look up a converter function by using the type name, parsed from the query column name, as the converter dictionary key. - The query column name must be wrapped with double quotes (``"``), + The query column name must be wrapped in double quotes (``"``), and the type name must be wrapped in square brackets (``[]``), .. code-block:: sql From 9ed49e4902026362f1fac09242359e71685e1123 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Thu, 13 Mar 2025 20:32:02 +0100 Subject: [PATCH 3/6] Update Doc/library/sqlite3.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- 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 eba4b8c625c548..0c8eb51c8f7549 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -464,7 +464,7 @@ Module constants using the type name, parsed from the query column name, as the converter dictionary key. The query column name must be wrapped in double quotes (``"``), - and the type name must be wrapped in square brackets (``[]``), + and the type name must be wrapped in square brackets (``[]``). .. code-block:: sql From 5cf5da0ed9c5b0464b5ff8c4756ac72809b8be4a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 17 Mar 2025 21:12:28 +0100 Subject: [PATCH 4/6] Use '.. note::' --- Doc/library/sqlite3.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 0c8eb51c8f7549..155b4af6505486 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -454,8 +454,10 @@ Module constants This flag may be combined with :const:`PARSE_COLNAMES` using the ``|`` (bitwise or) operator. - Generated fields (for example ``MAX(data)``) are returned as :class:`str`; - use :const:`!PARSE_COLNAMES` to enforce types for such queries. + .. note:: + + Generated fields (for example ``MAX(p)``) are returned as :class:`str`. + Use :const:`!PARSE_COLNAMES` to enforce types for such queries. .. data:: PARSE_COLNAMES From 72a3c119434af39752c0bad37e1bdfee5c580188 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 17 Mar 2025 23:18:00 +0100 Subject: [PATCH 5/6] Update sqlite3.rst --- 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 155b4af6505486..c615650b622f7f 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -465,7 +465,7 @@ Module constants :func:`connect` to look up a converter function by using the type name, parsed from the query column name, as the converter dictionary key. - The query column name must be wrapped in double quotes (``"``), + The query column name must be wrapped in double quotes (``"``) and the type name must be wrapped in square brackets (``[]``). .. code-block:: sql From 6ab0071067b0b6ca174e7b3258e0313656425452 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 17 Mar 2025 23:20:17 +0100 Subject: [PATCH 6/6] Update Doc/library/sqlite3.rst