cosalette

cosalette — An opinionated Python framework for IoT-to-MQTT bridges

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.

Project links

Data verified by PyPI on Jul 23, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.9.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ff-fab from gravatar.com ff-fab

Credits

Author: Fabian Koerner

GitHub Statistics

Data verified by PyPI on Jul 23, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.14

Provides Extra

mcp schema

Tags

iot mqtt home-automation asyncio framework

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cosalette-0.5.6.tar.gz (394.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

cosalette-0.5.6-cp314-abi3-win_amd64.whl (605.9 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.6-cp314-abi3-musllinux_1_2_x86_64.whl (949.4 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ x86-64

cosalette-0.5.6-cp314-abi3-musllinux_1_2_aarch64.whl (917.2 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.6-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (746.6 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ x86-64

cosalette-0.5.6-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (749.3 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.6-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (741.7 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.6-cp314-abi3-macosx_11_0_arm64.whl (711.7 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.6-cp314-abi3-macosx_10_12_x86_64.whl (714.1 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

Details for the file cosalette-0.5.6.tar.gz.

File metadata

  • Download URL: cosalette-0.5.6.tar.gz
  • Upload date:
  • Size: 394.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for cosalette-0.5.6.tar.gz
Algorithm Hash digest
SHA256 39ba2ac8be6f9dba094f31d92035b095d860b9c69c0f5529acf877c738bc8cba
MD5 05f8a1d198cadc68f52bb0fe29eab65f
BLAKE2b-256 155e41ded175582ee8838703486993f5bf713c7dbc12ea518eac1d22b6440fdc

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6.tar.gz:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cosalette-0.5.6-cp314-abi3-win_amd64.whl.

File metadata

  • Download URL: cosalette-0.5.6-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 605.9 kB
  • Tags: CPython 3.14+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for cosalette-0.5.6-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4a41963a00773096aac717f03c943cceedc99ba1d8a17ac98f3b50a49703bedd
MD5 04de25c8294c8c20e3063d1e4f846f46
BLAKE2b-256 22845a703f944757881e922b7621827c34b3da66a39958673f8064d934f1715c

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6-cp314-abi3-win_amd64.whl:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cosalette-0.5.6-cp314-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.6-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 25cd4a3d8dd6f6d786a02224e6da8b6e08d1451190529d66e57ee9ea3f25b93f
MD5 f7d96774314c3f834ac8d6b50e853890
BLAKE2b-256 a72935aa13bb62ebe4c224fd2a77f131badbcfd46006a52ef4ea823c40b41c7f

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6-cp314-abi3-musllinux_1_2_x86_64.whl:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cosalette-0.5.6-cp314-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.6-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 3f890d6167acccb7a09cea48dd808c84bd64b32b74750275e1f9393c0ffe24d3
MD5 ef09ce2819d4b98da9fb55148a77275f
BLAKE2b-256 ab11b712d52c999d9b6418d07d2a3a18d59963a4450276249d35da5157e93c18

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6-cp314-abi3-musllinux_1_2_aarch64.whl:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cosalette-0.5.6-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.6-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fd9f967ab8e84715ccc1fab4dbf0efc673e3dc52194c253884d1c88ccc1ab76f
MD5 f9dbcf58e27c9522c26b3a5fb12b5242
BLAKE2b-256 0add8c850be0bebab08c8f85857a791ec6effbd2e13775bd1ebe4e186a771b93

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cosalette-0.5.6-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl.

File metadata

File hashes

Hashes for cosalette-0.5.6-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 f3d78f877d292ca25f1171942382d88cbf8f8d8464321faaeba3deba1fc27316
MD5 5b9f28200bcf9cdc6b478d2d071469ee
BLAKE2b-256 961b7bbe58e2b4d47f854f12c300f6d3bc9fec749de5f1a8594685bc26dc14b5

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cosalette-0.5.6-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.6-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3aad50381ce0407060fd30aa561fe2d7f8e76d337bd103ebe70a1f92db7b64f2
MD5 23842d1162c7095ab619ac41f20fc4ea
BLAKE2b-256 7ee93f80163cced24ddc350454174a481a8553e54558e19206ad1b96ee3d7b6f

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cosalette-0.5.6-cp314-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.6-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 dcb10fe875af9d029e19048824e54917dd07284fd369b75dfe13ca37b8628424
MD5 2cd7f5d5ed559a9247233793921e43fd
BLAKE2b-256 6e0d928cbe3e2d608d21515ff04adba0e244e14e02a9f715bf86ed8b8ea329d3

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6-cp314-abi3-macosx_11_0_arm64.whl:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cosalette-0.5.6-cp314-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.6-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 226fcb0f7bb115b5eacbedb52443296c702b9c84d84cb718c7fcd4df61cb5176
MD5 a20d20e6768700def87de02a01eb4190
BLAKE2b-256 94831bad19008c2f5dbfa657e7b159e79a1b5e355b6dd3779fc39e0de9b4d662

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.6-cp314-abi3-macosx_10_12_x86_64.whl:

Publisher: release-please.yml on ff-fab/cosalette

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.9.1

9 files

0.9.0

9 files

0.8.0

9 files

0.7.1

9 files

0.7.0

9 files

0.6.3

9 files

0.6.2

9 files

0.6.1

9 files

0.6.0

9 files

0.5.10

9 files

0.5.9

9 files

0.5.8

9 files

0.5.7

9 files

This release

0.5.6 This release

9 files

0.5.5

9 files

0.5.4

9 files

0.5.3

9 files

0.5.2

9 files

0.5.1

9 files

0.5.0

9 files

0.4.5

9 files

0.4.4

9 files

0.4.3

9 files

0.4.2

9 files

0.4.0

9 files

0.3.13

9 files

0.3.12

9 files

0.3.11

9 files

0.3.10

9 files

0.3.9

9 files

0.3.8

9 files

0.3.7

9 files

0.3.6

9 files

0.3.5

9 files

0.3.4

9 files

0.3.3

9 files

0.3.2

9 files

0.3.1

9 files

0.3.0

9 files

0.2.1

13 files

0.2.0

12 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page