Metadata-Version: 2.4
Name: parley-mqtt
Version: 1.0.0
Summary: Request/response RPC over MQTT — the Python (asyncio) reference implementation of Parley protocol v1.
Project-URL: Homepage, https://github.com/serionist/parley-mqtt
Project-URL: Repository, https://github.com/serionist/parley-mqtt
Project-URL: Issues, https://github.com/serionist/parley-mqtt/issues
Project-URL: Documentation, https://github.com/serionist/parley-mqtt/blob/main/docs/protocol.md
Author: The Parley Authors
License-Expression: MIT
License-File: LICENSE
Keywords: asyncio,iot,mqtt,request-response,rpc
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy==2.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Requires-Dist: ruff==0.15.22; extra == 'dev'
Description-Content-Type: text/markdown

# parley-mqtt

**Request/response RPC over MQTT** — the Python (asyncio) reference implementation of the Parley v1 protocol.

> Install `parley-mqtt`; import `parley`. (The bare `parley` distribution name on PyPI is an
> unrelated project; the module name is unchanged.)

Parley turns the MQTT broker you already share into something you can make *requests* over:
call a command on another device, stream progress while it runs, cancel it, and receive one
typed result — success or a clear error. It is a small library, not a server: it rides your
existing MQTT connection and never holds your broker credentials or TLS material.

One wire protocol, four parallel reference libraries — **C#**, **TypeScript/JS**, **Python**, and
**C++ (ESP32/Arduino)** — so a .NET service, an edge script, a Python service, and firmware can all
call each other. `parley-mqtt` is the Python one.

- Pure `asyncio`; fully type-hinted (`py.typed`); CPython 3.10+.
- Zero required runtime dependencies — you supply a live MQTT connection through a tiny adapter
  you write.
- At-most-once execution correct even at QoS 0; retries, dedup, heartbeats, progress, real
  cancellation, and six built-in error codes.

```bash
pip install parley-mqtt
```

```python
from parley import ParleyCommander, ParleyTopics

topics = ParleyTopics("home/backup/req", "home/backup/hb", "home/backup/prg", "home/backup/res")
commander: ParleyCommander[Req, Prog, Res, Err] = ParleyCommander(adapter, topics)

result = await commander.execute({"target": "photos"}, on_progress=lambda p: print(p["percent"]))
if result.is_success:
    assert result.value is not None
    print(result.value["bytesWritten"])
else:
    assert result.error is not None
    print(result.error.code)
```

## Documentation

- **Repository:** <https://github.com/serionist/parley-mqtt>
- **The wire protocol (normative):** <https://github.com/serionist/parley-mqtt/blob/main/docs/protocol.md>
- **Worked Python example:** <https://github.com/serionist/parley-mqtt/tree/main/examples/python>
- **Design notes:** <https://github.com/serionist/parley-mqtt/blob/main/docs/design.md>

## License

[MIT](https://github.com/serionist/parley-mqtt/blob/main/LICENSE) © The Parley Authors.
