Type checking

.github/workflows/publish.yml

@@ -52,10 +52,10 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: {{ matrix.python-version }}
+        python-version: ${{ matrix.python-version }}
 
     - name: Install dependencies
-      run: uv sync --all-extras -p {{ matrix.python-version }}
+      run: uv sync --all-extras -p ${{ matrix.python-version }}
 
     - name: Build
       run: uv build

.github/workflows/typecheck.yml

@@ -0,0 +1,38 @@
+name: Typecheck
+
+on:
+  pull_request:
+    paths-ignore:
+      - '**/*.md'
+      - 'AUTHORS'
+
+jobs:
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - name: Check out Git repository
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@d9e0f98d3fc6adb07d1e3d37f3043649ddad06a1 # v6.5.0
+        with:
+          version: 'latest'
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run mypy
+        run: |
+          cd litecli
+          uv run --no-sync --frozen -- python -m ensurepip
+          uv run --no-sync --frozen -- python -m mypy --no-pretty --install-types --non-interactive .

AGENTS.md

@@ -10,16 +10,30 @@
 - Create env: `python -m venv .venv && source .venv/bin/activate`.
 - Install dev deps: `pip install -e .[dev]`.
 - Run all tests + coverage: `tox`.
-- Style/lint (ruff): `tox -e style` (runs `ruff check --fix` and `ruff format`).
 - Extra tests with SQLean: `tox -e sqlean` (installs `[sqlean]` extras).
-- Run tests directly: `pytest -v` or focused: `pytest -k keyword`.
+- Run tests directly: `pytest -q` or focused: `pytest -k keyword`.
 - Launch CLI locally: `litecli path/to.db`.
 
+### Ruff (lint/format)
+- Full style pass: `tox -e style` (runs `ruff check --fix` and `ruff format`).
+- Direct commands:
+  - Lint: `ruff check` (add `--fix` to auto-fix)
+  - Format: `ruff format`
+
+### Mypy (type checking)
+- Repo-wide (recommended): `mypy --explicit-package-bases .`
+- Per-package: `mypy --explicit-package-bases litecli`
+- Notes:
+  - Config is in `pyproject.toml` (target Python 3.9, stricter settings).
+  - Use `--explicit-package-bases` to avoid module discovery issues when running outside tox.
+
 ## Coding Style & Naming Conventions
 - Formatter/linter: Ruff (configured via `.pre-commit-config.yaml` and `tox`).
 - Indentation: 4 spaces. Line length: 140 (see `pyproject.toml`).
 - Naming: modules/functions/variables `snake_case`; classes `CamelCase`; tests `test_*.py`.
 - Keep imports sorted and unused code removed (ruff enforces).
+- Use lowercase type hints for dict, list, tuples etc.
+- Use | for Unions and | None for Optional.
 
 ## Testing Guidelines
 - Framework: Pytest with coverage (`coverage run -m pytest` via tox).
@@ -33,6 +47,11 @@
 - PRs: include clear description, steps to reproduce/verify, and screenshots or snippets for CLI output when helpful. Use the PR template.
 - Ensure CI passes (tests + ruff). Re-run `tox -e style` before requesting review.
 
+## Changelog Discipline
+- Always add an "Unreleased" section at the top of `CHANGELOG.md` when making changes.
+- Keep entries succinct; avoid overly detailed technical notes.
+- Group under "Features", "Bug Fixes", and "Internal" when applicable.
+
 ## Security & Configuration Tips
 - Do not commit local databases or secrets. Use files under `tests/data/` for fixtures.
 - User settings live outside the repo; document defaults by editing `litecli/liteclirc`.

CHANGELOG.md

@@ -1,9 +1,13 @@
-## Upcoming (TBC)
+## Upcoming (TBD)
 
 ### Bug Fixes
 
 * Avoid Click 8.1.* to prevent messing up the pager when the PAGER env var has a string with spaces.
 
+### Internal
+
+- Add type checking using mypy.
+
 ## 1.16.0 - 2025-08-16
 
 ### Features

litecli/__init__.py

@@ -1,3 +1,6 @@
+# type: ignore
+from __future__ import annotations
+
 import importlib.metadata
 
 __version__ = importlib.metadata.version("litecli")

litecli/clibuffer.py

@@ -1,14 +1,18 @@
-from __future__ import unicode_literals
+from __future__ import annotations
+
+from typing import Any
 
 from prompt_toolkit.enums import DEFAULT_BUFFER
-from prompt_toolkit.filters import Condition
+from prompt_toolkit.filters import Condition, Filter
 from prompt_toolkit.application import get_app
 
 
-def cli_is_multiline(cli):
+def cli_is_multiline(cli: Any) -> Filter:
     @Condition
-    def cond():
-        doc = get_app().layout.get_buffer_by_name(DEFAULT_BUFFER).document
+    def cond() -> bool:
+        buf = get_app().layout.get_buffer_by_name(DEFAULT_BUFFER)
+        assert buf is not None
+        doc = buf.document
 
         if not cli.multi_line:
             return False
@@ -18,7 +22,7 @@ def cond():
     return cond
 
 
-def _multiline_exception(text):
+def _multiline_exception(text: str) -> bool:
     orig = text
     text = text.strip()
 

litecli/clistyle.py

@@ -1,18 +1,20 @@
-from __future__ import unicode_literals
+from __future__ import annotations
 
 import logging
 
+
 import pygments.styles
 from pygments.token import string_to_tokentype, Token
 from pygments.style import Style as PygmentsStyle
 from pygments.util import ClassNotFound
 from prompt_toolkit.styles.pygments import style_from_pygments_cls
 from prompt_toolkit.styles import merge_styles, Style
+from prompt_toolkit.styles.style import _MergedStyle
 
 logger = logging.getLogger(__name__)
 
 # map Pygments tokens (ptk 1.0) to class names (ptk 2.0).
-TOKEN_TO_PROMPT_STYLE = {
+TOKEN_TO_PROMPT_STYLE: dict[Token, str] = {
     Token.Menu.Completions.Completion.Current: "completion-menu.completion.current",
     Token.Menu.Completions.Completion: "completion-menu.completion",
     Token.Menu.Completions.Meta.Current: "completion-menu.meta.completion.current",
@@ -41,10 +43,10 @@
 }
 
 # reverse dict for cli_helpers, because they still expect Pygments tokens.
-PROMPT_STYLE_TO_TOKEN = {v: k for k, v in TOKEN_TO_PROMPT_STYLE.items()}
+PROMPT_STYLE_TO_TOKEN: dict[str, Token] = {v: k for k, v in TOKEN_TO_PROMPT_STYLE.items()}
 
 
-def parse_pygments_style(token_name, style_object, style_dict):
+def parse_pygments_style(token_name: str, style_object: PygmentsStyle | dict, style_dict: dict[str, str]) -> tuple[Token, str]:
     """Parse token type and style string.
 
     :param token_name: str name of Pygments token. Example: "Token.String"
@@ -53,20 +55,20 @@ def parse_pygments_style(token_name, style_object, style_dict):
 
     """
     token_type = string_to_tokentype(token_name)
-    try:
+    if isinstance(style_object, PygmentsStyle):
         other_token_type = string_to_tokentype(style_dict[token_name])
         return token_type, style_object.styles[other_token_type]
-    except AttributeError:
+    else:
         return token_type, style_dict[token_name]
 
 
-def style_factory(name, cli_style):
+def style_factory(name: str, cli_style: dict[str, str]) -> _MergedStyle:
     try:
         style = pygments.styles.get_style_by_name(name)
     except ClassNotFound:
         style = pygments.styles.get_style_by_name("native")
 
-    prompt_styles = []
+    prompt_styles: list[tuple[str, str]] = []
     # prompt-toolkit used pygments tokens for styling before, switched to style
     # names in 2.0. Convert old token types to new style names, for backwards compatibility.
     for token in cli_style:
@@ -84,11 +86,11 @@ def style_factory(name, cli_style):
             # https://github.com/jonathanslenders/python-prompt-toolkit/blob/master/prompt_toolkit/styles/defaults.py
             prompt_styles.append((token, cli_style[token]))
 
-    override_style = Style([("bottom-toolbar", "noreverse")])
+    override_style: Style = Style([("bottom-toolbar", "noreverse")])
     return merge_styles([style_from_pygments_cls(style), override_style, Style(prompt_styles)])
 
 
-def style_factory_output(name, cli_style):
+def style_factory_output(name: str, cli_style: dict[str, str]) -> PygmentsStyle:
     try:
         style = pygments.styles.get_style_by_name(name).styles
     except ClassNotFound:

litecli/clitoolbar.py

@@ -1,17 +1,17 @@
-from __future__ import unicode_literals
+from __future__ import annotations
+
+from typing import Callable, Any
 
 from prompt_toolkit.key_binding.vi_state import InputMode
 from prompt_toolkit.enums import EditingMode
 from prompt_toolkit.application import get_app
 
 
-def create_toolbar_tokens_func(cli, show_fish_help):
-    """
-    Return a function that generates the toolbar tokens.
-    """
+def create_toolbar_tokens_func(cli: Any, show_fish_help: Callable[[], bool]) -> Callable[[], list[tuple[str, str]]]:
+    """Return a function that generates the toolbar tokens."""
 
-    def get_toolbar_tokens():
-        result = []
+    def get_toolbar_tokens() -> list[tuple[str, str]]:
+        result: list[tuple[str, str]] = []
         result.append(("class:bottom-toolbar", " "))
 
         if cli.multi_line:
@@ -35,7 +35,7 @@ def get_toolbar_tokens():
     return get_toolbar_tokens
 
 
-def _get_vi_mode():
+def _get_vi_mode() -> str:
     """Get the current vi mode for display."""
     return {
         InputMode.INSERT: "I",

litecli/completion_refresher.py

@@ -1,4 +1,8 @@
+from __future__ import annotations
+
 import threading
+from typing import Callable
+
 from .packages.special.main import COMMANDS
 from collections import OrderedDict
 
@@ -7,13 +11,18 @@
 
 
 class CompletionRefresher(object):
-    refreshers = OrderedDict()
+    refreshers: dict[str, Callable] = OrderedDict()
 
-    def __init__(self):
-        self._completer_thread = None
+    def __init__(self) -> None:
+        self._completer_thread: threading.Thread | None = None
         self._restart_refresh = threading.Event()
 
-    def refresh(self, executor, callbacks, completer_options=None):
+    def refresh(
+        self,
+        executor: SQLExecute,
+        callbacks: Callable | list[Callable],
+        completer_options: dict | None = None,
+    ) -> list[tuple]:
         """Creates a SQLCompleter object and populates it with the relevant
         completion suggestions in a background thread.
 
@@ -32,10 +41,11 @@ def refresh(self, executor, callbacks, completer_options=None):
             self._restart_refresh.set()
             return [(None, None, None, "Auto-completion refresh restarted.")]
         else:
-            if executor.dbname == ":memory:":
+            if executor.dbname == ":memory":
                 # if DB is memory, needed to use same connection
                 # So can't use same connection with different thread
                 self._bg_refresh(executor, callbacks, completer_options)
+                return [(None, None, None, "Auto-completion refresh started in the background.")]
             else:
                 self._completer_thread = threading.Thread(
                     target=self._bg_refresh,
@@ -44,19 +54,17 @@ def refresh(self, executor, callbacks, completer_options=None):
                 )
                 self._completer_thread.daemon = True
                 self._completer_thread.start()
-                return [
-                    (
-                        None,
-                        None,
-                        None,
-                        "Auto-completion refresh started in the background.",
-                    )
-                ]
-
-    def is_refreshing(self):
-        return self._completer_thread and self._completer_thread.is_alive()
-
-    def _bg_refresh(self, sqlexecute, callbacks, completer_options):
+                return [(None, None, None, "Auto-completion refresh started in the background.")]
+
+    def is_refreshing(self) -> bool:
+        return bool(self._completer_thread and self._completer_thread.is_alive())
+
+    def _bg_refresh(
+        self,
+        sqlexecute: SQLExecute,
+        callbacks: Callable | list[Callable],
+        completer_options: dict,
+    ) -> None:
         completer = SQLCompleter(**completer_options)
 
         e = sqlexecute
@@ -90,41 +98,42 @@ def _bg_refresh(self, sqlexecute, callbacks, completer_options):
             callback(completer)
 
 
-def refresher(name, refreshers=CompletionRefresher.refreshers):
+def refresher(name: str, refreshers: dict[str, Callable] = CompletionRefresher.refreshers) -> Callable:
     """Decorator to add the decorated function to the dictionary of
     refreshers. Any function decorated with a @refresher will be executed as
     part of the completion refresh routine."""
 
-    def wrapper(wrapped):
+    def wrapper(wrapped: Callable) -> Callable:
         refreshers[name] = wrapped
         return wrapped
 
     return wrapper
 
 
 @refresher("databases")
-def refresh_databases(completer, executor):
+def refresh_databases(completer: SQLCompleter, executor: SQLExecute) -> None:
     completer.extend_database_names(executor.databases())
 
 
 @refresher("schemata")
-def refresh_schemata(completer, executor):
+def refresh_schemata(completer: SQLCompleter, executor: SQLExecute) -> None:
     # name of the current database.
     completer.extend_schemata(executor.dbname)
     completer.set_dbname(executor.dbname)
 
 
 @refresher("tables")
-def refresh_tables(completer, executor):
-    completer.extend_relations(executor.tables(), kind="tables")
-    completer.extend_columns(executor.table_columns(), kind="tables")
+def refresh_tables(completer: SQLCompleter, executor: SQLExecute) -> None:
+    table_cols = list(executor.table_columns())
+    completer.extend_relations(table_cols, kind="tables")
+    completer.extend_columns(table_cols, kind="tables")
 
 
 @refresher("functions")
-def refresh_functions(completer, executor):
+def refresh_functions(completer: SQLCompleter, executor: SQLExecute) -> None:
     completer.extend_functions(executor.functions())
 
 
 @refresher("special_commands")
-def refresh_special(completer, executor):
-    completer.extend_special_commands(COMMANDS.keys())
+def refresh_special(completer: SQLCompleter, executor: SQLExecute) -> None:
+    completer.extend_special_commands(list(COMMANDS.keys()))