[3.10] pythongh-95273: Improve sqlite3.complete_statement docs (pytho…

…nGH-95840) Co-authored-by: Ezio Melotti <[email protected]> Co-authored-by: CAM Gerlach <[email protected]>. (cherry picked from commit e6623e7) Co-authored-by: Erlend E. Aasland <[email protected]>
erlend-aasland · Aug 12, 2022 · 49443c0 · 49443c0
1 parent bfaa071
commit 49443c0
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 38 deletions.
diff --git a/Doc/includes/sqlite3/complete_statement.py b/Doc/includes/sqlite3/complete_statement.py
diff --git 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, /)