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,37 @@
+from _sqlite3 import SQLITE_KEYWORDS
+from contextlib import contextmanager
+
+_completion_matches = []
+
+
+def _complete(text, state):
+    global _completion_matches
+    if state == 0:
+        text_upper = text.upper()
+        _completion_matches = [c for c in SQLITE_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 import SQLITE_KEYWORDS
 from sqlite3.__main__ import main as cli
+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_for_nothing(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 = list(map(str.strip, output_lines[start:end]))
+        self.assertEqual(candidates, sorted(SQLITE_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.

Modules/_sqlite/module.c

@@ -32,6 +32,7 @@
 #include "microprotocols.h"
 #include "row.h"
 #include "blob.h"
+#include "util.h"
 
 #if SQLITE_VERSION_NUMBER < 3015002
 #error "SQLite 3.15.2 or higher required"
@@ -404,6 +405,42 @@ pysqlite_error_name(int rc)
     return NULL;
 }
 
+static int
+add_keyword_tuple(PyObject *module)
+{
+    int count = sqlite3_keyword_count();
+    PyObject *keywords = PyTuple_New(count);
+    if (keywords == NULL) {
+        goto error;
+    }
+    for (int i = 0; i < count; i++) {
+        const char *keyword;
+        int size;
+        int result = sqlite3_keyword_name(i, &keyword, &size);
+        if (result != SQLITE_OK) {
+            pysqlite_state *state = pysqlite_get_state(module);
+            set_error_from_code(state, result);
+            goto error;
+        }
+        PyObject *kwd = PyUnicode_FromStringAndSize(keyword, size);
+        if (!kwd) {
+            goto error;
+        }
+        if (PyTuple_SetItem(keywords, i, kwd) < 0) {
+            Py_DECREF(kwd);
+            goto error;
+        }
+    }
+    if (PyModule_Add(module, "SQLITE_KEYWORDS", keywords) < 0) {
+        goto error;
+    }
+    return 0;
+
+error:
+    Py_XDECREF(keywords);
+    return -1;
+}
+
 static int
 add_integer_constants(PyObject *module) {
 #define ADD_INT(ival)                                           \
@@ -702,6 +739,11 @@ module_exec(PyObject *module)
         goto error;
     }
 
+    /* Set the keyword tuple */
+    if (add_keyword_tuple(module) < 0) {
+        goto error;
+    }
+
     if (PyModule_AddStringConstant(module, "sqlite_version", sqlite3_libversion())) {
         goto error;
     }