cosalette
What is cosalette?
cosalette lets you build IoT-to-MQTT bridge daemons in Python with minimal boilerplate. You define devices (telemetry pollers or command handlers), register hardware adapters, and the framework handles MQTT wiring, structured logging, health reporting, error publishing, and graceful lifecycle management.
Quick Example
import cosalette
app = cosalette.App(name="sensor2mqtt", version="0.1.0")
@app.telemetry("sensor", interval=5.0)
async def sensor() -> dict[str, object]:
return {"temperature": 21.5, "humidity": 55.0}
if __name__ == "__main__":
app.run()
See the full Quickstart for a complete walkthrough.
Router Composition (Multi-Module Apps)
For production apps, use Router to organize devices into separate modules without
circular imports:
# sensors.py
import cosalette
router = cosalette.Router(prefix="sensors")
@router.telemetry("temperature", interval=30)
async def read_temp() -> dict[str, object]:
return {"celsius": 22.5}
# main.py
import cosalette
from sensors import router
app = cosalette.App(name="home2mqtt", version="1.0.0")
app.include_router(router)
# → publishes to: home2mqtt/sensors/temperature/state
See Router Composition for full patterns.
Typed Contracts & Schema Inspection
cosalette supports Pydantic-validated payloads and typed returns for type-safe command handlers and telemetry, plus dependency injection for shared logic:
from typing import Annotated
from pydantic import BaseModel
import cosalette
app = cosalette.App(name="thermo2mqtt", version="1.0.0")
class SetpointCommand(BaseModel):
value: float
unit: str = "celsius"
class ThermostatState(BaseModel):
setpoint: float
unit: str
def get_device_id() -> str:
return "thermo-001"
@app.command("thermostat/set")
async def set_temp(
cmd: Annotated[SetpointCommand, cosalette.Payload()],
device_id: Annotated[str, cosalette.Depends(get_device_id)],
) -> ThermostatState:
return ThermostatState(setpoint=cmd.value, unit=cmd.unit)
Inspect the contract to generate AsyncAPI docs or consumer artifacts:
cosalette manifest myapp.main:app # JSON AsyncAPI 3.0.0
cosalette manifest myapp.main:app --table # human-readable table
Or programmatically:
doc = app.asyncapi() # returns dict conforming to AsyncAPI 3.0.0
See Contract-First Route Design and Schema Enforcement for full details.
Key Features
- Declarative device registration — define telemetry and command devices with
@app.telemetry(),@app.command(), and@app.device()(guide) - Hexagonal architecture — protocol-based ports keep hardware adapters swappable and testable (concept)
- Lifespan + dependency injection — structured startup/teardown and type-based DI for adapters, settings, and shared state (guide)
- Command routing — use sub-topic handlers and
ctx.commands()for clean control flows (guide) - Flexible scheduling — combine fixed intervals, Quartz cron, and
ctx.sleep_until()wall-clock timing - Publish strategies — emit on change, on cadence, or with composed rules (concept)
- Health checks + auto-restart — monitor adapters and recover from wedged hardware automatically (concept)
- Persistence — store state with JSON, SQLite, or in-memory backends plus save policies (concept)
- Schema-aware integrations — validate payloads and generate consumer artifacts from AsyncAPI schemas (guide)
- AI-assisted development — optional MCP tools plus packaged instructions for Copilot and other IDE-native agents (guide)
Installation
pip install cosalette
Or with uv:
uv add cosalette
To include the optional MCP server for IDE-native AI agent integration (VS Code Copilot, Cursor, Windsurf, Claude Code):
uv add 'cosalette[mcp]'
pip install 'cosalette[mcp]'
See the MCP Server guide for setup and tool reference.
Contributing
See CONTRIBUTING.md for development setup, commands, project structure, and code quality standards.
Documentation
Full documentation is published at
ff-fab.github.io/cosalette. Development docs
tracking the main branch are available at
Dev Docs (latest).
| Section | What you'll find |
|---|---|
| Getting Started | Installation, quickstart tutorial |
| Concepts | Architecture, lifecycle, health checks, filters, persistence |
| How-To Guides | Telemetry, commands, adapters, lifespan DI, schema, testing, MCP |
| Reference | API docs, CLI options, payload schemas |
| ADRs | Architecture Decision Records |
License
MIT License. See LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for cosalette 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cosalette-0.11.0.tar.gz | 789.5 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| cosalette-0.11.0-cp314-abi3-win_amd64.whl | CPython 3.14 | abi3 | Windows x86-64 | Details |
| cosalette-0.11.0-cp314-abi3-musllinux_1_2_x86_64.whl | CPython 3.14 | abi3 | Linux musl 1.2+ x86-64 | Details |
| cosalette-0.11.0-cp314-abi3-musllinux_1_2_aarch64.whl | CPython 3.14 | abi3 | Linux musl 1.2+ ARM64 | Details |
| cosalette-0.11.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.14 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| cosalette-0.11.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl | CPython 3.14 | abi3 | Linux glibc 2.17+ ARMv7l | Details |
| cosalette-0.11.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.14 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| cosalette-0.11.0-cp314-abi3-macosx_11_0_arm64.whl | CPython 3.14 | abi3 | macOS 11.0+ ARM64 | Details |
| cosalette-0.11.0-cp314-abi3-macosx_10_12_x86_64.whl | CPython 3.14 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 10.2 MB
Release files / cosalette-0.11.0.tar.gz
| Download URL | cosalette-0.11.0.tar.gz |
|---|---|
| Size | 789.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
497cf4ce4e2ac908a0af47b0b2aad76258cf0abd68c4140b3d3c40e12946c365
|
|
BLAKE2b-256 checksum How to use checksums |
c8d38a700a884094a25dba9c14b519847868f2276d2a6a128165e110916099ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / cosalette-0.11.0-cp314-abi3-win_amd64.whl
| Download URL | cosalette-0.11.0-cp314-abi3-win_amd64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.14 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
2da0772cf63757af7c2c2abce3b43c810b5415c2b7ca5af7fc6ce8bc3890f802
|
|
BLAKE2b-256 checksum How to use checksums |
01b42ac16c4eef0a821952a3928ebc0511d9ba10f8facfec0fabd98f966dff0e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / cosalette-0.11.0-cp314-abi3-musllinux_1_2_x86_64.whl
| Download URL | cosalette-0.11.0-cp314-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.14 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
4c23930887c3abfdd6786381fbd26f509ed57a370028e9a04477947f174872f9
|
|
BLAKE2b-256 checksum How to use checksums |
814d21dc8e0dc4e18e17e3a6b477fa9031e2e77559e65ba903d98e9040b2cb51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / cosalette-0.11.0-cp314-abi3-musllinux_1_2_aarch64.whl
| Download URL | cosalette-0.11.0-cp314-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 1.3 MB |
| Tags | CPython 3.14 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
93780ab0aca0698e1086c71aba04f3c3b2f6415d059effd4f767880a878fda59
|
|
BLAKE2b-256 checksum How to use checksums |
a6bc635611ec759fdf9c0fbf97345bd5a6f32d138f4fee0bc3dcc39c68185cf8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / cosalette-0.11.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | cosalette-0.11.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.14 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
cdca8847da8cae9d3886e943075c4017bb6bdb27ad90207c19bf47c265791122
|
|
BLAKE2b-256 checksum How to use checksums |
f7eac54347be8c0876c6afbcf7c1b85bf90966217cfb04a58241163daf28f73c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / cosalette-0.11.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
| Download URL | cosalette-0.11.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.14 Linux glibc 2.17+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
36a224a06d9bc61b45a711671a5a3545300fd5d8826e2e4a0c801142dfe7c8c1
|
|
BLAKE2b-256 checksum How to use checksums |
f61543f5a2b1dba7cb07259663f0534b2ed9af08a2bc675c4a88f50039dd0946
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / cosalette-0.11.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | cosalette-0.11.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.14 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
edc3d2b5eb8c86dba1ef494243dd8c860df1b45f50c799bc7d53e1b942db0116
|
|
BLAKE2b-256 checksum How to use checksums |
5d71235342024df1563cbb320f76455922c0aeeacb735e4628c26f42818c8c3e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / cosalette-0.11.0-cp314-abi3-macosx_11_0_arm64.whl
| Download URL | cosalette-0.11.0-cp314-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.14 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
86ec93104fd6da52daeda5d272375199ca4b157f98abe0f7fffae5ddb6c7a415
|
|
BLAKE2b-256 checksum How to use checksums |
6ac6271ebb13e7f46c99cb65091c79d8745b35aa409d3513fa8a48f6ea317f99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / cosalette-0.11.0-cp314-abi3-macosx_10_12_x86_64.whl
| Download URL | cosalette-0.11.0-cp314-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.14 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
acdef324b33aa2372c921bd768ecc7000f0ef3d612c594bc74de190a7aba3869
|
|
BLAKE2b-256 checksum How to use checksums |
51afb866c03a81acc44f334dc9c14e9b940b1f4d7427083a32a5750e65aec089
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency log
