Type hints for sqlean.py - Python's sqlite3 + extensions.

Installation

pip install sqlean-stubs

or with uv:

uv add sqlean-stubs

Usage

Type hints enable IDE autocomplete and type checking for sqlean code:

from typing import Optional
import sqlean
def main_sqlean():
    print("Hello from try-sqlean-stubs!")
    conn: sqlean.Connection = sqlean.connect(":memory:")
    cursor: sqlean.Cursor = conn.cursor()
    # Create repos table
    cursor.execute("""
        CREATE TABLE repos (
            id INTEGER PRIMARY KEY,
            package_name TEXT NOT NULL,
            github_url TEXT NOT NULL
        )
    """)
    # Insert test data
    cursor.execute(
        "INSERT INTO repos (package_name, github_url) VALUES (?, ?)",
        ("sqlean.py", "https://github.com/nalgeon/sqlean.py")
    )
    cursor.execute(
        "INSERT INTO repos (package_name, github_url) VALUES (?, ?)",
        ("sqlean-stubs", "https://github.com/kracekumar/sqlean-stubs")
    )
    # Query the table
    cursor.execute("SELECT * FROM repos")
    # fetchone() returns Optional[Any]
    row: Optional[sqlean.Row] = cursor.fetchone()
    if row is not None:
        print(f"ID: {row[0]}, Package: {row[1]}, URL: {row[2]}")
    # User-defined functions
    def double(x: int) -> int:
        return x * 2
    conn.create_function("double", 1, double)
    conn.close()
if __name__ == "__main__":
    main_sqlean()

Benefits:

IDE autocomplete and navigation
Catch type errors before runtime with mypy or ty
Better code documentation and refactoring safety

Features

Complete type hints for Connection, Cursor, and Row objects
Support for custom factories and row factories
Type hints for user-defined functions and aggregates
Callbacks support (authorizer, progress handler, trace callback, busy handler)
Window function support
Extensions management API
Compatible with mypy, ty, pyright, and other type checkers

Requirements

Python 3.9 or later
pip, uv, or pipx for installation

Contributing

Development Setup

git clone https://github.com/nalgeon/sqlean-stubs.git
cd sqlean-stubs
uv sync

Running Tests

# Run all tests
uv run pytest tests/
# Linting
uv run ruff check .
# Type checking
uv run mypy tests/test_mypy.py
uv run ty check
# Test multiple Python versions (3.9-3.14)
uv run tox

Project Structure

sqlean/dbapi2.pyi - Main DB-API 2.0 interface
sqlean/extensions.pyi - Extension management API
sqlean/py.typed - PEP 561 marker file
tests/test_types.py - Runtime tests
tests/test_mypy.py - Type checking tests

Adding Type Hints

Update the .pyi stub file
Add runtime test in tests/test_types.py
Add type checking test in tests/test_mypy.py
Run pytest tests/, mypy tests/test_mypy.py, and ty check

Code Style

Follow PEP 484 for type hints
Use Optional[X] instead of X | None (Python 3.9 compatibility)
Use Literal types for constrained values
Include docstrings for complex types

Before Submitting

uv run ruff check .
uv run pytest tests/ -v
uv run mypy tests/test_mypy.py
uv run ty check

License

Zlib (same as sqlean.py)