Metadata-Version: 2.4
Name: dqlite-wire
Version: 0.3.0
Summary: Pure Python wire protocol implementation for dqlite
Project-URL: Homepage, https://github.com/letsdiscodev/python-dqlite-wire
Project-URL: Repository, https://github.com/letsdiscodev/python-dqlite-wire
Project-URL: Issues, https://github.com/letsdiscodev/python-dqlite-wire/issues
Author-email: Antoine Leclair <antoineleclair@gmail.com>
License-Expression: MIT
License-File: LICENSE.md
Keywords: database,distributed,dqlite,sqlite,wire-protocol
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Typing :: Typed
Requires-Python: >=3.13
Provides-Extra: dev
Requires-Dist: mypy>=1.0; 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-wire

Pure-Python codec for the [dqlite](https://dqlite.io/) wire protocol —
encode and decode the messages a dqlite server speaks.

[dqlite](https://dqlite.io/) is Canonical's distributed SQLite, built on
Raft. This package implements the bytes-on-the-wire layer: it turns
request/response objects into frames and back, following the
[official wire-protocol specification](https://canonical.com/dqlite/docs/reference/wire-protocol).
It does no networking, pooling, or SQL — just framing.

## Is this the package you want?

Probably not, unless you are building a driver or doing wire-level work
(a proxy, traffic capture/replay, a custom client). If you just want to
run SQL against dqlite from Python, use one of the higher layers — see
[The dqlite Python stack](#the-dqlite-python-stack) below.

## Installation

```bash
pip install dqlite-wire
```

Requires Python 3.13+.

## Usage

```python
from dqlitewire import encode_message, decode_message
from dqlitewire.messages import LeaderRequest

# Encode a request to bytes
data = encode_message(LeaderRequest())

# Decode bytes back into a message object
message = decode_message(data, is_request=True)
```

## The dqlite Python stack

This is the lowest 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](https://github.com/letsdiscodev/python-dqlite-dbapi) | 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** — this package | Wire-protocol codec |

**Most applications should use [dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi)
or [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite).**

## Documentation

- [Thread-safety](docs/thread-safety.md) — codec objects are single-owner; read this before sharing one.
- [Divergences from upstream](docs/divergences-from-upstream.md) — the
  defensive caps and stricter validations this codec adds on top of the C
  server and [go-dqlite](https://github.com/canonical/go-dqlite).

## Development

See [DEVELOPMENT.md](DEVELOPMENT.md) for setup and contribution guidelines.

## License

MIT
