dqlite-dbapi 0.2.2__tar.gz → 0.3.0__tar.gz

dqlite_dbapi-0.3.0/DEVELOPMENT.md

@@ -0,0 +1,100 @@
+# Development Guide
+
+## Prerequisites
+
+- Python 3.13+
+- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
+- Docker (for integration tests)
+
+## Setup
+
+Clone [dqlite-wire](https://github.com/letsdiscodev/python-dqlite-wire) and [dqlite-client](https://github.com/letsdiscodev/python-dqlite-client) alongside this checkout; `[tool.uv.sources]` in `pyproject.toml` points the sibling packages at `../python-dqlite-wire` and `../python-dqlite-client`, so `uv sync` picks up in-tree changes automatically.
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv sync --extra 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
+```
+
+## Comments and docstrings
+
+Keep comments and docstrings to a minimum — the code should be clear
+enough to stand on its own. Prefer renaming a function or variable over
+writing a comment to explain an unclear one.
+
+- Write a comment only when it captures something genuinely non-obvious
+  that the code cannot: a subtle invariant, a security caveat, a
+  workaround for an upstream bug, or a "why" a reader would otherwise
+  get wrong. Delete comments that merely restate what the code does.
+- Most functions need no docstring. Add a one-line docstring only when
+  it tells a reader something the name and signature do not. Avoid
+  multi-paragraph essays, param-by-param prose, and "Notes/Divergence"
+  sections.
+- Do not record rationale, history, or decision logs in comments — that
+  context belongs in the commit message and git history (`git blame`,
+  `git log -p`), where it stays attached to the change instead of aging
+  in the source.
+- Tooling directives (`# type:`, `# noqa`, `# pragma:`) are exempt —
+  keep them.
+
+When in doubt, leave it out: a missing explanation is a `git blame`
+away; a redundant or stale comment is noise every future reader pays
+for.
+
+## 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 = 2` (threads may share module and connections, not cursors)
+- `paramstyle = "qmark"` (question mark placeholders)

dqlite_dbapi-0.3.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: dqlite-dbapi
+Version: 0.3.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: Framework :: AsyncIO
+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: Programming Language :: Python :: 3.14
+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.4.0,>=0.3.0
+Requires-Dist: dqlite-wire<0.4.0,>=0.3.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
+
+A [PEP 249](https://peps.python.org/pep-0249/) (DB-API 2.0) driver for
+[dqlite](https://dqlite.io/), Canonical's distributed SQLite. If you have
+used Python's standard `sqlite3` module, this will feel familiar — same
+`connect()` / `cursor()` / `execute()` / `fetchone()` shape — but it talks
+to a replicated dqlite cluster over the network instead of a local file.
+
+It comes in two flavors from one package: a **synchronous** API
+(`dqlitedbapi`) and an **async** API (`dqlitedbapi.aio`).
+
+## Is this the package you want?
+
+Yes, if you want a drop-in-style database driver for dqlite — directly,
+or under a tool that expects a DB-API 2.0 driver. For SQLAlchemy
+specifically, use [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite)
+(it builds on this package).
+
+## Installation
+
+```bash
+pip install dqlite-dbapi
+```
+
+Requires Python 3.13+.
+
+## Usage
+
+### Sync
+
+```python
+import dqlitedbapi
+
+conn = dqlitedbapi.connect("localhost:9001")
+cur = conn.cursor()
+cur.execute("SELECT 1")
+print(cur.fetchone())
+conn.close()
+```
+
+### Async
+
+```python
+import asyncio
+from dqlitedbapi.aio import aconnect
+
+async def main():
+    conn = await aconnect("localhost:9001")
+    cur = conn.cursor()
+    await cur.execute("SELECT 1")
+    print(await cur.fetchone())
+    await conn.close()
+
+asyncio.run(main())
+```
+
+## Key facts
+
+- `apilevel = "2.0"`, `paramstyle = "qmark"` (`?` placeholders),
+  `threadsafety = 2`.
+- **Autocommit by default.** Unlike stdlib `sqlite3`, the driver does not
+  auto-`BEGIN` before a statement — wrap writes in an explicit transaction
+  when you need atomic multi-statement semantics. See
+  [Transactions](docs/transactions.md).
+- **Isolation is always SERIALIZABLE** — every write goes through Raft
+  consensus, every read is serializable.
+
+## The dqlite Python stack
+
+This is one of four layered packages. Each builds on the one below:
+
+| Package | Role |
+| --- | --- |
+| [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite) | SQLAlchemy 2.0 dialect |
+| **dqlite-dbapi** — this package | PEP 249 (DB-API 2.0) driver — sync & async |
+| [dqlite-client](https://github.com/letsdiscodev/python-dqlite-client) | Async wire client — pooling, leader discovery |
+| [dqlite-wire](https://github.com/letsdiscodev/python-dqlite-wire) | Wire-protocol codec |
+
+Using SQLAlchemy or an ORM? Prefer
+[sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite).
+
+## Documentation
+
+- [Transactions](docs/transactions.md) — the autocommit-by-default model and how to group statements.
+- [Differences from `sqlite3`](docs/differences-from-sqlite3.md) — what to
+  expect when porting from the stdlib module (and a server-version NULL
+  gotcha).
+- [Differences from `aiosqlite`](docs/differences-from-aiosqlite.md) — for
+  the async surface.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.
+
+## License
+
+MIT

dqlite_dbapi-0.3.0/README.md

@@ -0,0 +1,97 @@
+# dqlite-dbapi
+
+A [PEP 249](https://peps.python.org/pep-0249/) (DB-API 2.0) driver for
+[dqlite](https://dqlite.io/), Canonical's distributed SQLite. If you have
+used Python's standard `sqlite3` module, this will feel familiar — same
+`connect()` / `cursor()` / `execute()` / `fetchone()` shape — but it talks
+to a replicated dqlite cluster over the network instead of a local file.
+
+It comes in two flavors from one package: a **synchronous** API
+(`dqlitedbapi`) and an **async** API (`dqlitedbapi.aio`).
+
+## Is this the package you want?
+
+Yes, if you want a drop-in-style database driver for dqlite — directly,
+or under a tool that expects a DB-API 2.0 driver. For SQLAlchemy
+specifically, use [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite)
+(it builds on this package).
+
+## Installation
+
+```bash
+pip install dqlite-dbapi
+```
+
+Requires Python 3.13+.
+
+## Usage
+
+### Sync
+
+```python
+import dqlitedbapi
+
+conn = dqlitedbapi.connect("localhost:9001")
+cur = conn.cursor()
+cur.execute("SELECT 1")
+print(cur.fetchone())
+conn.close()
+```
+
+### Async
+
+```python
+import asyncio
+from dqlitedbapi.aio import aconnect
+
+async def main():
+    conn = await aconnect("localhost:9001")
+    cur = conn.cursor()
+    await cur.execute("SELECT 1")
+    print(await cur.fetchone())
+    await conn.close()
+
+asyncio.run(main())
+```
+
+## Key facts
+
+- `apilevel = "2.0"`, `paramstyle = "qmark"` (`?` placeholders),
+  `threadsafety = 2`.
+- **Autocommit by default.** Unlike stdlib `sqlite3`, the driver does not
+  auto-`BEGIN` before a statement — wrap writes in an explicit transaction
+  when you need atomic multi-statement semantics. See
+  [Transactions](docs/transactions.md).
+- **Isolation is always SERIALIZABLE** — every write goes through Raft
+  consensus, every read is serializable.
+
+## The dqlite Python stack
+
+This is one of four layered packages. Each builds on the one below:
+
+| Package | Role |
+| --- | --- |
+| [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite) | SQLAlchemy 2.0 dialect |
+| **dqlite-dbapi** — this package | PEP 249 (DB-API 2.0) driver — sync & async |
+| [dqlite-client](https://github.com/letsdiscodev/python-dqlite-client) | Async wire client — pooling, leader discovery |
+| [dqlite-wire](https://github.com/letsdiscodev/python-dqlite-wire) | Wire-protocol codec |
+
+Using SQLAlchemy or an ORM? Prefer
+[sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite).
+
+## Documentation
+
+- [Transactions](docs/transactions.md) — the autocommit-by-default model and how to group statements.
+- [Differences from `sqlite3`](docs/differences-from-sqlite3.md) — what to
+  expect when porting from the stdlib module (and a server-version NULL
+  gotcha).
+- [Differences from `aiosqlite`](docs/differences-from-aiosqlite.md) — for
+  the async surface.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.
+
+## License
+
+MIT

dqlite_dbapi-0.3.0/docs/differences-from-aiosqlite.md

@@ -0,0 +1,42 @@
+# Differences from `aiosqlite`
+
+The async surface lives under `dqlitedbapi.aio` and mirrors the sync
+`dqlitedbapi` surface, plus async-specific `aconnect` / `AsyncConnection` /
+`AsyncCursor`.
+
+For easy porting from [aiosqlite](https://github.com/omnilib/aiosqlite), the
+full PEP 249 module surface is re-exported under `dqlitedbapi.aio` from one
+namespace: the module attributes (`apilevel`, `threadsafety`, `paramstyle`,
+`sqlite_version`, `sqlite_version_info`), the exception hierarchy (`Warning`,
+`Error`, `InterfaceError`, `DatabaseError`, `DataError`, `OperationalError`,
+`IntegrityError`, `InternalError`, `ProgrammingError`, `NotSupportedError`),
+the type constructors (`Date`, `Time`, `Timestamp`, `DateFromTicks`,
+`TimeFromTicks`, `TimestampFromTicks`, `Binary`), the type sentinels
+(`STRING`, `BINARY`, `NUMBER`, `DATETIME`, `ROWID`, `UNKNOWN`), the `Row`
+factory and `DescriptionTuple`, `register_adapter` / `unregister_adapter`, and
+the `NotSupportedError` stubs for stdlib-only APIs.
+
+## The one difference to watch
+
+**`AsyncConnection.__aexit__` does not close the connection.** It commits or
+rolls back per the block outcome and leaves the connection reusable — matching
+stdlib `sqlite3.Connection.__exit__` and PEP 249 §7. `aiosqlite`'s
+`__aexit__` *does* close (it tears down its proxy thread and sqlite3
+connection).
+
+So when porting from aiosqlite, add an explicit `await conn.close()` (or use a
+pool) where you relied on close-on-exit:
+
+```python
+# aiosqlite — closes on aexit:
+async with aiosqlite.connect(":memory:") as conn:
+    ...
+
+# dqlitedbapi.aio — does NOT close on aexit (matches stdlib sqlite3):
+async with await dqlitedbapi.aio.aconnect(...) as conn:
+    ...
+    await conn.close()   # explicit
+```
+
+Everything else under [Differences from `sqlite3`](differences-from-sqlite3.md)
+applies to the async surface too.

dqlite_dbapi-0.3.0/docs/differences-from-sqlite3.md

@@ -0,0 +1,99 @@
+# Differences from `sqlite3`
+
+`dqlite-dbapi` is shaped like the stdlib `sqlite3` module, but it talks to a
+replicated cluster over the network rather than a local file. This page
+covers the differences you are most likely to notice when porting code.
+
+## Things you'll likely notice
+
+- **Autocommit by default.** No implicit `BEGIN` before DML — the opposite
+  of stdlib's implicit-transaction model. See
+  [Transactions](transactions.md).
+- **One statement per `execute()`.** `cursor.execute("SELECT 1; SELECT 2;")`
+  raises `ProgrammingError` (client-side, before any network round-trip).
+  Split into separate calls. There is no `executescript()` — it raises
+  `NotSupportedError`.
+- **`qmark` parameters only.** Use `?` placeholders. Stdlib also accepts
+  `:name`; this driver advertises only `qmark` and rejects mappings with
+  `ProgrammingError`.
+- **Foreign keys are enforced by default.** dqlite defaults every fresh
+  connection to `PRAGMA foreign_keys = ON` — the opposite of stdlib/pysqlite,
+  which default `OFF`. Issue `PRAGMA foreign_keys = OFF` per connection for
+  SQLite's legacy unenforced behavior.
+- **SERIALIZABLE isolation only.** Every statement is ordered by Raft;
+  weaker isolation levels are not exposed.
+- **`connect()` timeouts differ from stdlib.** stdlib's `timeout` is the
+  busy (lock-wait) budget; here `timeout` is a per-RPC-phase deadline and
+  the busy budget is the separate `busy_timeout` argument. `connect()` also
+  exposes safety caps — `max_message_size`, `max_continuation_frames`,
+  `max_total_rows` — and `trust_server_heartbeat`.
+- **Result sets are fully materialized at `execute()` time.** Stdlib streams
+  rows lazily from the C engine; dqlite drains every continuation frame into
+  the cursor's in-memory buffer before `execute()` returns, and `fetchone()`
+  / `fetchmany()` / `fetchall()` iterate that buffer. For large queries, cap
+  memory with `max_total_rows` (forwarded from `connect()`) or shape queries
+  with an explicit `LIMIT`.
+- **No SQLite extension APIs.** `create_function`, `create_aggregate`,
+  `create_window_function`, `iterdump`, `backup`, `set_authorizer`,
+  `serialize`, `blobopen`, `executescript`, and `register_converter` have no
+  server-side counterpart in dqlite; their stubs raise `NotSupportedError`.
+- **`rowcount` after SELECT is `len(rows)`.** Stdlib returns `-1` for queries.
+  dqlite knows the full result at execute time, so it reports the count.
+  `rowcount` stays `-1` for non-result paths, for all PRAGMA statements (read
+  or write — matching stdlib), and for a never-executed cursor.
+
+## NULL in BOOLEAN/DATETIME columns depends on the server version
+
+A 2026 dqlite server change (upstream commit `f30fc99`) changed how a NULL
+cell is encoded in columns declared `BOOLEAN`, `DATE`, `DATETIME`, or
+`TIMESTAMP`:
+
+- **Before**: a NULL came back as `False` (for `BOOLEAN`) or `""` (for
+  datetime types) — indistinguishable from a real value.
+- **After**: a NULL comes back as `None`.
+
+There is no handshake that distinguishes the two server versions, and the
+driver decodes faithfully whatever the server sends. Code like
+`if row[0] is None:` will silently miss rows on an old cluster and start
+matching after an upgrade. Check your dqlite cluster version before relying
+on `is None` for these columns.
+
+## Minor / edge-case differences
+
+You can usually ignore these, but they are here so nothing surprises you:
+
+- **`lastrowid` is `None` (not `0`) before the first INSERT.** After the
+  first INSERT both drivers agree and keep the value sticky across
+  UPDATE/DELETE/DDL.
+- **`fetchmany(0)` returns `[]`** (PEP 249 read literally). Pass `None` or
+  omit the argument to default to `arraysize`. `fetchmany(negative)` raises
+  `ProgrammingError`.
+- **`execute("")` raises `ProgrammingError`** (empty/whitespace/comment-only
+  SQL). Stdlib treats it as a no-op.
+- **Empty result sets report the `UNKNOWN` type code** in
+  `description[i][1]` (importable from `dqlitedbapi`). Test it with
+  `type_code == UNKNOWN`; for column types on an empty result, query
+  `PRAGMA table_info(...)`.
+- **CTE-prefixed DML** (`WITH ... INSERT/UPDATE/DELETE`) sets `lastrowid` and
+  reports `rowcount` as the affected-row count. That `rowcount` is a dqlite
+  extra: stdlib sqlite3 returns `-1` for CTE-prefixed DML (it counts only
+  non-CTE DML). `WITH ... SELECT` and `WITH ... RETURNING` return rows as usual.
+
+### Type-code sentinels: compare with `==`, not `in {}`
+
+The PEP 249 type sentinels (`STRING`, `BINARY`, `NUMBER`, `DATETIME`,
+`ROWID`) match a `description` type code through `__eq__`, and each wraps
+several wire types (`NUMBER` covers INTEGER+FLOAT+BOOLEAN; `DATETIME` covers
+DATE+TIMESTAMP+ISO8601). A bare wire-int type code does not *hash* equal to a
+sentinel, so set/dict membership silently returns `False`:
+
+```python
+type_code = cur.description[i][1]
+if type_code == STRING or type_code == NUMBER:   # correct
+    ...
+if type_code in {STRING, NUMBER}:                # WRONG: silently False
+    ...
+```
+
+Stdlib `sqlite3` doesn't export these sentinels at all, so the
+chained-equality form is also the cross-driver-portable idiom.

dqlite_dbapi-0.3.0/docs/transactions.md

@@ -0,0 +1,84 @@
+# Transactions
+
+## Autocommit by default
+
+`dqlite-dbapi` does **not** issue an implicit `BEGIN` before your DML. Each
+statement runs in the dqlite engine's autocommit mode unless you have
+explicitly opened a transaction.
+
+This differs from stdlib `sqlite3` and `psycopg`, which auto-`BEGIN` on the
+first DML. It matches the dqlite C and Go reference clients, which have the
+same opt-in contract. If you are porting code that relied on implicit
+transactions, add explicit `BEGIN` calls to recover atomic multi-statement
+semantics.
+
+Note that **isolation is always SERIALIZABLE** regardless — every write
+goes through Raft consensus and every read is serializable. Only the
+*grouping* of statements into one transaction is opt-in.
+
+## Grouping statements into a transaction
+
+Issue an explicit `BEGIN` through a cursor, then `commit()` / `rollback()`
+on the connection:
+
+```python
+cur = conn.cursor()
+cur.execute("BEGIN")
+cur.execute("INSERT INTO t VALUES (?)", (1,))
+cur.execute("INSERT INTO t VALUES (?)", (2,))
+conn.commit()       # or conn.rollback()
+```
+
+Under the default session mode (`immediate`) a bare `BEGIN` / `BEGIN
+TRANSACTION` is rewritten to `BEGIN IMMEDIATE`, so the deferred-to-write
+upgrade can't fail later with `SQLITE_BUSY_SNAPSHOT`; an explicit `DEFERRED`
+/ `IMMEDIATE` / `EXCLUSIVE` qualifier is passed through unchanged. dqlite's
+Raft FSM serializes the transaction across the cluster regardless of the
+qualifier, so the qualifier changes only lock-acquisition timing on the
+leader, never isolation.
+
+The session mode is selected with the `session_mode` connect argument (or the
+`DQLITE_SESSION_MODE` environment variable): `immediate` (default; rewrites a
+bare `BEGIN`), `deferred` / `exclusive` (no rewrite), or `read_only` (issues
+`PRAGMA query_only = 1`).
+
+The connection also works as a context manager (matching stdlib `sqlite3`):
+the `with conn:` block commits on clean exit and rolls back on exception.
+It does **not** close the connection — the connection stays reusable.
+
+## `commit()` / `rollback()` details
+
+- Calling `commit()` / `rollback()` before any query has run is a silent
+  no-op (the driver won't open a TCP connection just to send a COMMIT).
+- Calling them with no active transaction (e.g. right after DDL) is also a
+  silent success, matching stdlib `sqlite3`.
+- **Commit failures propagate.** Silent swallowing would risk hiding data
+  loss, so a failing commit raises.
+
+## `isolation_level`
+
+The `Connection.isolation_level` attribute exists for pre-3.12 stdlib
+parity. The setter accepts `None` and the legacy qualifier values (`""`,
+`"DEFERRED"`, `"IMMEDIATE"`, `"EXCLUSIVE"`, case-insensitive) as no-ops; the
+getter returns the last value set (default `None`). Any other value —
+including `"SERIALIZABLE"` and `"AUTOCOMMIT"` — raises `ProgrammingError`,
+because the qualifier cannot change dqlite's single serialized isolation
+level.
+
+## Leader flips during COMMIT
+
+If the leader loses leadership *after* the COMMIT entry was submitted, the
+write is in doubt — Raft may already have replicated it — and the driver
+raises `AmbiguousCommitError` (an `OperationalError` subclass, so
+`except OperationalError` still catches it). Use idempotent DML (`INSERT OR
+REPLACE`, `UPDATE` on a unique key) or an out-of-band state check before
+retrying. A plain not-leader rejection *before* the entry was submitted is a
+clean failure (the write definitely did not apply) and raises a plain
+`OperationalError`.
+
+## With SQLAlchemy
+
+If you use [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite),
+the dialect emits `BEGIN` for every `engine.begin()` / `connection.begin()`
+block — you don't manage `BEGIN` yourself. The autocommit-by-default
+behavior above applies only to direct dbapi users.

dqlite_dbapi-0.3.0/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dqlite-dbapi"
+version = "0.3.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",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Database :: Database Engines/Servers",
+    "Topic :: Database :: Front-Ends",
+    "Typing :: Typed",
+]
+dependencies = [
+    "dqlite-client>=0.3.0,<0.4.0",
+    "dqlite-wire>=0.3.0,<0.4.0",
+]
+
+[tool.uv.sources]
+dqlite-client = { path = "../python-dqlite-client", editable = true }
+dqlite-wire = { path = "../python-dqlite-wire", editable = true }
+
+[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"]
+
+# Hatchling's default file-selection would already ship ``py.typed`` via
+# ``packages``, but declaring it explicitly is the documented PEP 561
+# pattern and makes the intent obvious to anyone auditing the wheel.
+[tool.hatch.build.targets.wheel.force-include]
+"src/dqlitedbapi/py.typed" = "dqlitedbapi/py.typed"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = [
+    # Promote deprecations to errors so the suite catches stdlib
+    # deprecation surface under the CPython version the workspace
+    # already runs CI on (3.13/3.14). Whitelist genuine third-party
+    # noise with explicit ``ignore:<pattern>:DeprecationWarning:<module>``
+    # entries below, with a comment explaining the upstream tracker.
+    "error::DeprecationWarning",
+    "error::PendingDeprecationWarning",
+]
+
+[tool.mypy]
+strict = true
+python_version = "3.13"
+# Tests live under ``tests/`` with no ``__init__.py``; mypy needs
+# ``explicit_package_bases`` (or namespace packages) to avoid the
+# duplicate-conftest module-name collision when scanning sibling
+# integration/ subdirectories. ``mypy_path`` mirrors the
+# ``pythonpath = ["src"]`` declared for pytest so the source files
+# resolve under the package name (``dqlitedbapi``), not the layout
+# path (``src.dqlitedbapi``).
+explicit_package_bases = true
+mypy_path = "src"
+
+# Tests use a few patterns that mypy's strict mode flags but are
+# correct at runtime. Disabling these codes only inside ``tests.*``
+# keeps strict typing on production code while letting the test suite
+# use idiomatic patterns without per-line ``# type: ignore`` noise:
+#
+# * ``method-assign`` — monkey-patching bound methods
+#   (``conn.execute = fake_execute``) is the standard way to inject a
+#   fake without subclassing.
+# * ``no-untyped-def`` / ``no-untyped-call`` — pytest fixtures and
+#   small helpers are conventionally written without type annotations.
+# * ``comparison-overlap`` — ``assert SomeIntEnum.FOO == 0`` is the
+#   canonical "this enum matches its int value" pin against a
+#   reference table; mypy's literal-type narrowing incorrectly flags
+#   it as non-overlapping even though IntEnum's ``__eq__`` works.
+[[tool.mypy.overrides]]
+module = "tests.*"
+disable_error_code = ["method-assign", "no-untyped-def", "no-untyped-call", "comparison-overlap"]
+
+[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