Initial commit

Author: antoineleclair

.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+
+# Distribution
+dist/
+build/

DEVELOPMENT.md

@@ -0,0 +1,76 @@
+# Development Guide
+
+## Prerequisites
+
+- Python 3.13+
+- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
+- Docker (for integration tests)
+
+## Setup
+
+Start by also cloning [dqlite-wire](https://github.com/letsdiscodev/python-dqlite-wire) and [dqlite-client](https://github.com/letsdiscodev/python-dqlite-client).
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv venv --python 3.13
+uv pip install -e "../python-dqlite-wire" -e "../python-dqlite-client" -e ".[dev]"
+```
+
+## Development Tools
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| **pytest** | Testing framework | `pytest` |
+| **ruff** | Linter (replaces flake8, isort, etc.) | `ruff check` |
+| **ruff format** | Code formatter (replaces black) | `ruff format` |
+| **mypy** | Static type checker | `mypy src` |
+
+## Running Tests
+
+```bash
+# Run unit tests only
+.venv/bin/pytest tests/ --ignore=tests/integration
+
+# Run all tests (requires Docker cluster)
+cd ../dqlite-test-cluster && docker compose up -d
+.venv/bin/pytest tests/
+```
+
+## Linting & Formatting
+
+```bash
+# Lint
+.venv/bin/ruff check src tests
+
+# Auto-fix lint issues
+.venv/bin/ruff check --fix src tests
+
+# Format
+.venv/bin/ruff format src tests
+```
+
+## Type Checking
+
+```bash
+.venv/bin/mypy src
+```
+
+## Pre-commit Workflow
+
+```bash
+.venv/bin/ruff format src tests
+.venv/bin/ruff check --fix src tests
+.venv/bin/mypy src
+.venv/bin/pytest tests/ --ignore=tests/integration
+```
+
+## PEP 249 Compliance
+
+This package implements the DB-API 2.0 specification (PEP 249):
+
+- `apilevel = "2.0"`
+- `threadsafety = 1` (threads may share module, not connections)
+- `paramstyle = "qmark"` (question mark placeholders)

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoine Leclair and Greg Sadetsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,51 @@
+# dqlite-dbapi
+
+PEP 249 compliant interface for [dqlite](https://dqlite.io/).
+
+## Installation
+
+```bash
+pip install dqlite-dbapi
+```
+
+## Sync Usage
+
+```python
+import dqlitedbapi
+
+conn = dqlitedbapi.connect("localhost:9001")
+cursor = conn.cursor()
+cursor.execute("SELECT 1")
+print(cursor.fetchone())
+conn.close()
+```
+
+## Async Usage
+
+```python
+import asyncio
+from dqlitedbapi.aio import aconnect
+
+async def main():
+    conn = await aconnect("localhost:9001")
+    cursor = await conn.cursor()
+    await cursor.execute("SELECT 1")
+    print(await cursor.fetchone())
+    await conn.close()
+
+asyncio.run(main())
+```
+
+## PEP 249 Compliance
+
+- `apilevel = "2.0"`
+- `threadsafety = 1`
+- `paramstyle = "qmark"`
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.
+
+## License
+
+MIT

pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dqlite-dbapi"
+version = "0.1.0"
+description = "PEP 249 (DB-API 2.0) compliant interface for dqlite"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [{ name = "Antoine Leclair", email = "antoineleclair@gmail.com" }]
+keywords = ["dqlite", "sqlite", "distributed", "database", "dbapi", "pep249"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+    "Topic :: Database :: Front-Ends",
+    "Typing :: Typed",
+]
+dependencies = ["dqlite-client>=0.1.0"]
+
+[project.urls]
+Homepage = "https://github.com/letsdiscodev/python-dqlite-dbapi"
+Repository = "https://github.com/letsdiscodev/python-dqlite-dbapi"
+Issues = "https://github.com/letsdiscodev/python-dqlite-dbapi/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=4.0", "pytest-asyncio>=0.23", "mypy>=1.0", "ruff>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dqlitedbapi"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+strict = true
+python_version = "3.13"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["dqlitedbapi", "dqliteclient", "dqlitewire"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true

src/dqlitedbapi/__init__.py

@@ -0,0 +1,98 @@
+"""PEP 249 compliant interface for dqlite."""
+
+from dqlitedbapi.connection import Connection
+from dqlitedbapi.cursor import Cursor
+from dqlitedbapi.exceptions import (
+    DatabaseError,
+    DataError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+from dqlitedbapi.types import (
+    BINARY,
+    DATETIME,
+    NUMBER,
+    ROWID,
+    STRING,
+    Binary,
+    Date,
+    DateFromTicks,
+    Time,
+    TimeFromTicks,
+    Timestamp,
+    TimestampFromTicks,
+)
+
+# PEP 249 module-level attributes
+apilevel = "2.0"
+threadsafety = 1  # Threads may share the module, but not connections
+paramstyle = "qmark"  # Question mark style: WHERE name=?
+
+# SQLite compatibility attributes (for SQLAlchemy)
+# dqlite uses SQLite 3.x internally
+sqlite_version_info = (3, 35, 0)
+sqlite_version = "3.35.0"
+
+__all__ = [
+    # Module attributes
+    "apilevel",
+    "threadsafety",
+    "paramstyle",
+    # Functions
+    "connect",
+    # Classes
+    "Connection",
+    "Cursor",
+    # Exceptions
+    "Warning",
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "DataError",
+    "OperationalError",
+    "IntegrityError",
+    "InternalError",
+    "ProgrammingError",
+    "NotSupportedError",
+    # Type constructors
+    "Date",
+    "Time",
+    "Timestamp",
+    "DateFromTicks",
+    "TimeFromTicks",
+    "TimestampFromTicks",
+    "Binary",
+    # Type objects
+    "STRING",
+    "BINARY",
+    "NUMBER",
+    "DATETIME",
+    "ROWID",
+]
+
+__version__ = "0.1.0"
+
+
+def connect(
+    address: str,
+    *,
+    database: str = "default",
+    timeout: float = 10.0,
+) -> Connection:
+    """Connect to a dqlite database.
+
+    Args:
+        address: Node address in "host:port" format
+        database: Database name to open
+        timeout: Connection timeout in seconds
+
+    Returns:
+        A Connection object
+    """
+    return Connection(address, database=database, timeout=timeout)