[Python-checkins] [3.11] gh-95273: Improve sqlite3.complete_statement docs (GH-95840) (#95917)

[erlend-aasland]

https://github.com/python/cpython/commit/bd86e09ab9f6f49e7c973de591187d82c5382682
commit: bd86e09ab9f6f49e7c973de591187d82c5382682
branch: 3.11
author: Erlend E. Aasland <erlend.aasland at protonmail.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2022-08-12T09:34:26+02:00
summary:

[3.11] gh-95273: Improve sqlite3.complete_statement docs (GH-95840) (#95917)

Co-authored-by: Ezio Melotti <ezio.melotti at gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach at Gerlach.CAM>.
(cherry picked from commit e6623e7083ce08a247e5df169bcc749f99327823)

Co-authored-by: Erlend E. Aasland <erlend.aasland at protonmail.com>

files:
D Doc/includes/sqlite3/complete_statement.py
M Doc/library/sqlite3.rst

diff --git a/Doc/includes/sqlite3/complete_statement.py b/Doc/includes/sqlite3/complete_statement.py
deleted file mode 100644
index a5c947969910..000000000000
--- a/Doc/includes/sqlite3/complete_statement.py
+++ /dev/null
@@ -1,33 +0,0 @@
-# A minimal SQLite shell for experiments
-
-import sqlite3
-
-con = sqlite3.connect(":memory:")
-con.isolation_level = None
-cur = con.cursor()
-
-buffer = ""
-
-print("Enter your SQL commands to execute in sqlite3.")
-print("Enter a blank line to exit.")
-
-while True:
-    line = input()
-    if line == "":
-        break
-    buffer += line
-    if sqlite3.complete_statement(buffer):
-        try:
-            buffer = buffer.strip()
-            cur.execute(buffer)
-
-            if buffer.lstrip().upper().startswith("SELECT"):
-                print(cur.fetchall())
-        except sqlite3.Error as e:
-            err_msg = str(e)
-            err_code = e.sqlite_errorcode
-            err_name = e.sqlite_errorname
-            print(f"{err_name} ({err_code}): {err_msg}")
-        buffer = ""
-
-con.close()
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 1afb8c87b389..b4b98a50d8b7 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -222,14 +222,22 @@ Module functions
 
 .. function:: complete_statement(statement)
 
-   Returns ``True`` if the string *statement* contains one or more complete SQL
-   statements terminated by semicolons. It does not verify that the SQL is
-   syntactically correct, only that there are no unclosed string literals and the
-   statement is terminated by a semicolon.
-
-   This can be used to build a shell for SQLite, as in the following example:
-
-   .. literalinclude:: ../includes/sqlite3/complete_statement.py
+   Return ``True`` if the string *statement* appears to contain
+   one or more complete SQL statements.
+   No syntactic verification or parsing of any kind is performed,
+   other than checking that there are no unclosed string literals
+   and the statement is terminated by a semicolon.
+
+   For example::
+
+      >>> sqlite3.complete_statement("SELECT foo FROM bar;")
+      True
+      >>> sqlite3.complete_statement("SELECT foo")
+      False
+
+   This function may be useful during command-line input
+   to determine if the entered text seems to form a complete SQL statement,
+   or if additional input is needed before calling :meth:`~Cursor.execute`.
 
 .. function:: enable_callback_tracebacks(flag, /)