gh-133390: Support SQL keyword completion for sqlite3 CLI

Doc/whatsnew/3.15.rst

@@ -89,6 +89,13 @@ New modules
 Improved modules
 ================
 
+sqlite3
+-------
+
+* Support keyword completion in the :mod:`sqlite3` command-line interface.
+  (Contributed by Long Tan in :gh:`133393`.)
+
+
 ssl
 ---
 

Lib/sqlite3/__main__.py

@@ -12,6 +12,8 @@
 from textwrap import dedent
 from _colorize import get_theme, theme_no_color
 
+from ._completer import enable_completer
+
 
 def execute(c, sql, suppress_errors=True, theme=theme_no_color):
     """Helper that wraps execution of SQL code.
@@ -136,12 +138,9 @@ def main(*args):
             execute(con, args.sql, suppress_errors=False, theme=theme)
         else:
             # No SQL provided; start the REPL.
-            console = SqliteInteractiveConsole(con, use_color=True)
-            try:
-                import readline  # noqa: F401
-            except ImportError:
-                pass
-            console.interact(banner, exitmsg="")
+            with enable_completer():
+                console = SqliteInteractiveConsole(con, use_color=True)
+                console.interact(banner, exitmsg="")
     finally:
         con.close()
 

Lib/sqlite3/_completer.py

@@ -0,0 +1,62 @@
+from contextlib import contextmanager
+
+
+KEYWORDS = ("ABORT", "ACTION", "ADD", "AFTER", "ALL", "ALTER", "ALWAYS",
+            "ANALYZE", "AND", "AS", "ASC", "ATTACH", "AUTOINCREMENT",
+            "BEFORE", "BEGIN", "BETWEEN", "BY", "CASCADE", "CASE", "CAST",
+            "CHECK", "COLLATE", "COLUMN", "COMMIT", "CONFLICT",
+            "CONSTRAINT", "CREATE", "CROSS", "CURRENT", "CURRENT_DATE",
+            "CURRENT_TIME", "CURRENT_TIMESTAMP", "DATABASE", "DEFAULT",
+            "DEFERRABLE", "DEFERRED", "DELETE", "DESC", "DETACH",
+            "DISTINCT", "DO", "DROP", "EACH", "ELSE", "END", "ESCAPE",
+            "EXCEPT", "EXCLUDE", "EXCLUSIVE", "EXISTS", "EXPLAIN", "FAIL",
+            "FILTER", "FIRST", "FOLLOWING", "FOR", "FOREIGN", "FROM",
+            "FULL", "GENERATED", "GLOB", "GROUP", "GROUPS", "HAVING", "IF",
+            "IGNORE", "IMMEDIATE", "IN", "INDEX", "INDEXED", "INITIALLY",
+            "INNER", "INSERT", "INSTEAD", "INTERSECT", "INTO", "IS",
+            "ISNULL", "JOIN", "KEY", "LAST", "LEFT", "LIKE", "LIMIT",
+            "MATCH", "MATERIALIZED", "NATURAL", "NO", "NOT", "NOTHING",
+            "NOTNULL", "NULL", "NULLS", "OF", "OFFSET", "ON", "OR",
+            "ORDER", "OTHERS", "OUTER", "OVER", "PARTITION", "PLAN",
+            "PRAGMA", "PRECEDING", "PRIMARY", "QUERY", "RAISE", "RANGE",
+            "RECURSIVE", "REFERENCES", "REGEXP", "REINDEX", "RELEASE",
+            "RENAME", "REPLACE", "RESTRICT", "RETURNING", "RIGHT",
+            "ROLLBACK", "ROW", "ROWS", "SAVEPOINT", "SELECT", "SET",
+            "TABLE", "TEMP", "TEMPORARY", "THEN", "TIES", "TO",
+            "TRANSACTION", "TRIGGER", "UNBOUNDED", "UNION", "UNIQUE",
+            "UPDATE", "USING", "VACUUM", "VALUES", "VIEW", "VIRTUAL",
+            "WHEN", "WHERE", "WINDOW", "WITH", "WITHOUT")
+
+_completion_matches = []
+
+def _complete(text, state):
+    global _completion_matches
+    if state == 0:
+        text_upper = text.upper()
+        _completion_matches = [c for c in KEYWORDS if c.startswith(text_upper)]
+    try:
+        return _completion_matches[state] + " "
+    except IndexError:
+        return None
+
+
+@contextmanager
+def enable_completer():
+    try:
+        import readline
+    except ImportError:
+        yield
+        return
+
+    old_completer = readline.get_completer()
+    try:
+        readline.set_completer(_complete)
+        if readline.backend == "editline":
+            # libedit uses "^I" instead of "tab"
+            command_string = "bind ^I rl_complete"
+        else:
+            command_string = "tab: complete"
+        readline.parse_and_bind(command_string)
+        yield
+    finally:
+        readline.set_completer(old_completer)

Lib/test/test_sqlite3/test_cli.py

@@ -1,14 +1,19 @@
 """sqlite3 CLI tests."""
 import sqlite3
+import textwrap
 import unittest
 
 from sqlite3.__main__ import main as cli
+from sqlite3._completer import KEYWORDS
+from test.support.import_helper import import_module
 from test.support.os_helper import TESTFN, unlink
+from test.support.pty_helper import run_pty
 from test.support import (
     captured_stdout,
     captured_stderr,
     captured_stdin,
     force_not_colorized_test_class,
+    requires_subprocess,
 )
 
 
@@ -200,5 +205,76 @@ def test_color(self):
             self.assertIn('\x1b[1;35mOperationalError (SQLITE_ERROR)\x1b[0m: '
                           '\x1b[35mnear "sel": syntax error\x1b[0m', err)
 
+
+@requires_subprocess()
+class CompletionTest(unittest.TestCase):
+    PS1 = "sqlite> "
+
+    @classmethod
+    def setUpClass(cls):
+        readline = import_module("readline")
+        if readline.backend == "editline":
+            raise unittest.SkipTest("libedit readline is not supported")
+
+    def write_input(self, input, env=None):
+        script = textwrap.dedent("""
+            import readline
+            readline.parse_and_bind("set colored-completion-prefix off")
+            from sqlite3.__main__ import main; main()
+        """)
+        return run_pty(script, input, env)
+
+    def test_keyword_completion(self):
+        # List candidates starting with 'S', there should be multiple matches.
+        input = b"S\t\tEL\t 1;\n.quit\n"
+        output = self.write_input(input)
+        self.assertIn(b"SELECT", output)
+        self.assertIn(b"SET", output)
+        self.assertIn(b"SAVEPOINT", output)
+        self.assertIn(b"(1,)", output)
+
+        # Keywords are completed in upper case for even lower case user input
+        input = b"sel\t\t 1;\n.quit\n"
+        output = self.write_input(input)
+        self.assertIn(b"SELECT", output)
+        self.assertIn(b"(1,)", output)
+
+    def test_nothing_to_complete(self):
+        input = b"xyzzy\t\t\b\b\b\b\b.quit\n"
+        # set NO_COLOR to disable coloring for self.PS1
+        output = self.write_input(input, env={"NO_COLOR": "1"})
+        output_lines = output.decode().splitlines()
+        line_num = next((i for i, line in enumerate(output_lines, 1)
+                         if line.startswith(f"{self.PS1}xyzzy")), -1)
+        self.assertNotEqual(line_num, -1)
+        # completions occupy lines, assert no extra lines when there is nothing
+        # to complete
+        self.assertEqual(line_num, len(output_lines))
+
+    def test_completion_order(self):
+        script = textwrap.dedent("""
+            import readline
+            readline.parse_and_bind("set colored-completion-prefix off")
+            # hide control sequences surrounding each candidate
+            readline.parse_and_bind("set colored-stats off")
+            # hide "Display all xxx possibilities? (y or n)"
+            readline.parse_and_bind("set completion-query-items 0")
+            # hide "--More--"
+            readline.parse_and_bind("set page-completions off")
+            # show candidates one per line
+            readline.parse_and_bind("set completion-display-width 0")
+            from sqlite3.__main__ import main; main()
+        """)
+        input = b"\t\t.quit\n"
+        output = run_pty(script, input, env={"NO_COLOR": "1"})
+        output_lines = output.decode().splitlines()
+        indices = [i for i, line in enumerate(output_lines)
+                   if line.startswith(self.PS1)]
+        self.assertEqual(len(indices), 2)
+        start, end = indices[0] + 1, indices[1]
+        candidates = tuple(map(str.strip, output_lines[start:end]))
+        self.assertEqual(candidates, KEYWORDS)
+
+
 if __name__ == "__main__":
     unittest.main()

Misc/ACKS

@@ -1864,6 +1864,7 @@ Neil Tallim
 Geoff Talvola
 Anish Tambe
 Musashi Tamura
+Long Tan
 William Tanksley
 Christian Tanzer
 Steven Taschuk

Misc/NEWS.d/next/Library/2025-05-05-03-14-08.gh-issue-133390.AuTggn.rst

@@ -0,0 +1 @@
+Support keyword completion in the :mod:`sqlite3` command-line interface.