dqlite-dbapi 0.1.0__tar.gz

dqlite_dbapi-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dqlite-dbapi
+    permissions:
+      id-token: write
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v6
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

dqlite_dbapi-0.1.0/.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/

dqlite_dbapi-0.1.0/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)

dqlite_dbapi-0.1.0/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.

dqlite_dbapi-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: dqlite-dbapi
+Version: 0.1.0
+Summary: PEP 249 (DB-API 2.0) compliant interface for dqlite
+Project-URL: Homepage, https://github.com/letsdiscodev/python-dqlite-dbapi
+Project-URL: Repository, https://github.com/letsdiscodev/python-dqlite-dbapi
+Project-URL: Issues, https://github.com/letsdiscodev/python-dqlite-dbapi/issues
+Author-email: Antoine Leclair <antoineleclair@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: database,dbapi,distributed,dqlite,pep249,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: dqlite-client>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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

dqlite_dbapi-0.1.0/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

dqlite_dbapi-0.1.0/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

dqlite_dbapi-0.1.0/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)

dqlite_dbapi-0.1.0/src/dqlitedbapi/aio/__init__.py

@@ -0,0 +1,31 @@
+"""Async PEP 249-style interface for dqlite."""
+
+from dqlitedbapi.aio.connection import AsyncConnection
+from dqlitedbapi.aio.cursor import AsyncCursor
+
+__all__ = [
+    "aconnect",
+    "AsyncConnection",
+    "AsyncCursor",
+]
+
+
+async def aconnect(
+    address: str,
+    *,
+    database: str = "default",
+    timeout: float = 10.0,
+) -> AsyncConnection:
+    """Connect to a dqlite database asynchronously.
+
+    Args:
+        address: Node address in "host:port" format
+        database: Database name to open
+        timeout: Connection timeout in seconds
+
+    Returns:
+        An AsyncConnection object
+    """
+    conn = AsyncConnection(address, database=database, timeout=timeout)
+    await conn.connect()
+    return conn

dqlite_dbapi-0.1.0/src/dqlitedbapi/aio/connection.py

@@ -0,0 +1,86 @@
+"""Async connection implementation for dqlite."""
+
+from typing import Any
+
+from dqliteclient import DqliteConnection
+from dqlitedbapi.aio.cursor import AsyncCursor
+from dqlitedbapi.exceptions import InterfaceError, OperationalError
+
+
+class AsyncConnection:
+    """Async database connection."""
+
+    def __init__(
+        self,
+        address: str,
+        *,
+        database: str = "default",
+        timeout: float = 10.0,
+    ) -> None:
+        """Initialize connection (does not connect yet).
+
+        Args:
+            address: Node address in "host:port" format
+            database: Database name to open
+            timeout: Connection timeout in seconds
+        """
+        self._address = address
+        self._database = database
+        self._timeout = timeout
+        self._async_conn: DqliteConnection | None = None
+        self._closed = False
+
+    async def connect(self) -> None:
+        """Establish the connection."""
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        if self._async_conn is not None:
+            return
+
+        self._async_conn = DqliteConnection(
+            self._address,
+            database=self._database,
+            timeout=self._timeout,
+        )
+        try:
+            await self._async_conn.connect()
+        except Exception as e:
+            self._async_conn = None
+            raise OperationalError(f"Failed to connect: {e}") from e
+
+    async def close(self) -> None:
+        """Close the connection."""
+        if self._async_conn is not None:
+            await self._async_conn.close()
+            self._async_conn = None
+        self._closed = True
+
+    async def commit(self) -> None:
+        """Commit any pending transaction."""
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        if self._async_conn is not None:
+            await self._async_conn.execute("COMMIT")
+
+    async def rollback(self) -> None:
+        """Roll back any pending transaction."""
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        if self._async_conn is not None:
+            await self._async_conn.execute("ROLLBACK")
+
+    async def cursor(self) -> AsyncCursor:
+        """Return a new AsyncCursor object."""
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+        return AsyncCursor(self)
+
+    async def __aenter__(self) -> "AsyncConnection":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()