From bbe34c5113c63b6ca4686ace57a6331534ed76a3 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 12:12:28 +0200 Subject: [PATCH 1/6] gh-95235: Document undocumented parameters in sqlite3 functions and methods --- Doc/library/sqlite3.rst | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 583a36d1ef46d6..60c2142869f461 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -583,7 +583,7 @@ Connection Objects .. method:: set_authorizer(authorizer_callback) - This routine registers a callback. The callback is invoked for each attempt to + Register callable *authorizer_callback* to be invoked for each attempt to access a column of a table in the database. The callback should return :const:`SQLITE_OK` if access is allowed, :const:`SQLITE_DENY` if the entire SQL statement should be aborted with an error and :const:`SQLITE_IGNORE` if the @@ -609,7 +609,7 @@ Connection Objects .. method:: set_progress_handler(progress_handler, n) - This routine registers a callback. The callback is invoked for every *n* + Register callback *progress_handler* to be invoked for every *n* instructions of the SQLite virtual machine. This is useful if you want to get called from SQLite during long-running operations, for example to update a GUI. @@ -624,7 +624,7 @@ Connection Objects .. method:: set_trace_callback(trace_callback) - Registers *trace_callback* to be called for each SQL statement that is + Register *trace_callback* to be called for each SQL statement that is actually executed by the SQLite backend. The only argument passed to the callback is the statement (as @@ -648,8 +648,10 @@ Connection Objects .. method:: enable_load_extension(enabled, /) - This routine allows/disallows the SQLite engine to load SQLite extensions - from shared libraries. SQLite extensions can define new functions, + Enable the SQLite engine to load SQLite extensions from shared libraries + if *enabled* is :const:`True`; + else, disallow loading SQLite extensions. + SQLite extensions can define new functions, aggregates or whole new virtual table implementations. One well-known extension is the fulltext-search extension distributed with SQLite. @@ -666,9 +668,9 @@ Connection Objects .. method:: load_extension(path, /) - This routine loads an SQLite extension from a shared library. You have to - enable extension loading with :meth:`enable_load_extension` before you can - use this routine. + Load an SQLite extension from a shared library located at *path*. + Enable extension loading with :meth:`enable_load_extension` before using + this API. Loadable extensions are disabled by default. See [#f1]_. @@ -877,8 +879,9 @@ Cursor Objects .. method:: execute(sql, parameters=(), /) - Execute an SQL statement. Values may be bound to the statement using - :ref:`placeholders `. + Execute SQL statement *sql*. + Bind values to the statement using :ref:`placeholders + ` that map to the parameters in *parameters*. :meth:`execute` will only execute a single SQL statement. If you try to execute more than one statement with it, it will raise a :exc:`ProgrammingError`. Use @@ -893,7 +896,7 @@ Cursor Objects .. method:: executemany(sql, seq_of_parameters, /) - Execute a :ref:`parameterized ` SQL command + Execute :ref:`parameterized ` SQL statement *sql* against all parameter sequences or mappings found in the sequence *seq_of_parameters*. It is also possible to use an :term:`iterator` yielding parameters instead of a sequence. @@ -908,7 +911,7 @@ Cursor Objects .. method:: executescript(sql_script, /) - Execute multiple SQL statements at once. + Execute the multiple SQL statements in *sql_script*. If there is a pending transaciton, an implicit ``COMMIT`` statement is executed first. No other implicit transaction control is performed; From d7b45093200fe21dbf05b25239581acbc998169f Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 12:16:12 +0200 Subject: [PATCH 2/6] Improve set_trace_callback --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 60c2142869f461..4892b151637502 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -624,8 +624,8 @@ Connection Objects .. method:: set_trace_callback(trace_callback) - Register *trace_callback* to be called for each SQL statement that is - actually executed by the SQLite backend. + Register callback *trace_callback* to be invoked for each SQL statement + that is actually executed by the SQLite backend. The only argument passed to the callback is the statement (as :class:`str`) that is being executed. The return value of the callback is From 2b3869d94e9ff2e3b042b6c88e269a61feeae234 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 12:16:48 +0200 Subject: [PATCH 3/6] callback => callable --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 4892b151637502..9069f0d52184bb 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -609,7 +609,7 @@ Connection Objects .. method:: set_progress_handler(progress_handler, n) - Register callback *progress_handler* to be invoked for every *n* + Register callable *progress_handler* to be invoked for every *n* instructions of the SQLite virtual machine. This is useful if you want to get called from SQLite during long-running operations, for example to update a GUI. @@ -624,7 +624,7 @@ Connection Objects .. method:: set_trace_callback(trace_callback) - Register callback *trace_callback* to be invoked for each SQL statement + Register callable *trace_callback* to be invoked for each SQL statement that is actually executed by the SQLite backend. The only argument passed to the callback is the statement (as From 97afd0ff60de48901dd91c98baaa1abd3fef0ac8 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Mon, 25 Jul 2022 17:23:00 +0200 Subject: [PATCH 4/6] Update Doc/library/sqlite3.rst Co-authored-by: CAM Gerlach --- 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 9069f0d52184bb..f666321473265a 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -911,7 +911,7 @@ Cursor Objects .. method:: executescript(sql_script, /) - Execute the multiple SQL statements in *sql_script*. + Execute the SQL statements in *sql_script*. If there is a pending transaciton, an implicit ``COMMIT`` statement is executed first. No other implicit transaction control is performed; From 92007db186b2f7ca82919f795d32d33778c27110 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Mon, 25 Jul 2022 17:23:11 +0200 Subject: [PATCH 5/6] Update Doc/library/sqlite3.rst Co-authored-by: CAM Gerlach --- Doc/library/sqlite3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index f666321473265a..1990528c53fc26 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -669,8 +669,8 @@ Connection Objects .. method:: load_extension(path, /) Load an SQLite extension from a shared library located at *path*. - Enable extension loading with :meth:`enable_load_extension` before using - this API. + Enable extension loading with :meth:`enable_load_extension` before + calling this method. Loadable extensions are disabled by default. See [#f1]_. From 856a0beb3cd145b4735caccc8f9ac2b8f811a0f5 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 25 Jul 2022 17:29:10 +0200 Subject: [PATCH 6/6] Address review --- Doc/library/sqlite3.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 1990528c53fc26..956079b9bf31b5 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -881,7 +881,8 @@ Cursor Objects Execute SQL statement *sql*. Bind values to the statement using :ref:`placeholders - ` that map to the parameters in *parameters*. + ` that map to the :term:`sequence` or :class:`dict` + *parameters*. :meth:`execute` will only execute a single SQL statement. If you try to execute more than one statement with it, it will raise a :exc:`ProgrammingError`. Use