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 14, 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 14, 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.2.tar.gz (378.0 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.2-cp314-abi3-win_amd64.whl (588.2 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.2-cp314-abi3-musllinux_1_2_x86_64.whl (931.7 kB view details)

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

cosalette-0.5.2-cp314-abi3-musllinux_1_2_aarch64.whl (899.7 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (728.7 kB view details)

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

cosalette-0.5.2-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (731.7 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.2-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (724.2 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.2-cp314-abi3-macosx_11_0_arm64.whl (693.9 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.2-cp314-abi3-macosx_10_12_x86_64.whl (696.3 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.2.tar.gz
  • Upload date:
  • Size: 378.0 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.2.tar.gz
Algorithm Hash digest
SHA256 5b09e2b845d21b90f603f3a33ff5c60ca6b913b49d738f1668ccfc8a73e4ff96
MD5 41b28043d2e52f6dd5e87902018f4123
BLAKE2b-256 48db6f504f3e0b477c9925263aa59141c1e51d2ed160141bcf5caa86368e10aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2.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.2-cp314-abi3-win_amd64.whl.

File metadata

  • Download URL: cosalette-0.5.2-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 588.2 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.2-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4a3ca5d7085699cf5081846700dd880349f1f4f0b746a321795272cc7d11dbc0
MD5 6178b251f3d46fa8c42838849c943e33
BLAKE2b-256 002fc3c1a48055f4995a8100237ef0fa3fb4424a95883d0e477ad92d2f385fb0

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2-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.2-cp314-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.2-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 1c82af2e85c95e2ec513a115a1283f6936f166379ecf8cbe6d9a792f04f75c9d
MD5 3c08c6ac2b5ad8807be9c400a2c0591d
BLAKE2b-256 1bf73f4985dd590dd9455df8cfd938b044d57d7e347d125b7f81d14f531f50ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2-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.2-cp314-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.2-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 eaabf4fd9f6023d6c2a91ea2fffb84fd29d3efc6c232641be9c1192062b97691
MD5 db9cb2ef5fc51e2b1cfb06ad605c683e
BLAKE2b-256 6fd34c034d73c4ac40d1916d6738d4d8d7192e61a938066c380355233ae9c33c

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2-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.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 01c6722f77e2c717aab57183b9f9e0f2859b0e9895be3e202fd1bed85054dbe6
MD5 de8fabd51dba8892f9543c8b5aab77c6
BLAKE2b-256 cda4bd31c0af9eab83509ce819863a3a55e92b60711d403e6df94fbf230de9ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2-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.2-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl.

File metadata

File hashes

Hashes for cosalette-0.5.2-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 f13c099587d2fcdd6a4f305880a63f14d6de0d707c7b9add0ce85d27f1044ab8
MD5 0c9c05532cf0a47a3e260cdc3b0a982a
BLAKE2b-256 56a1efa9136a97b031789e1e5bb22bd292c8deb889ccffef6e831851e31671c4

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2-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.2-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.2-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 08a6dbe801d109f81dfb54099c7e5abb4e904071532f7e200fbdb14bd3979eea
MD5 e183211d5df37a87da8c04286b3fac4f
BLAKE2b-256 0af5cddcfc4ed256234a8daf8942f4f62ace379885474465e65e530bc334a75e

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2-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.2-cp314-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.2-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 567f9e03e4aab3da32482f9a667443ff8e543a60e87ae0d090350c826f4c8545
MD5 beb81351f13ab535ab2cb1f2eba117d8
BLAKE2b-256 d2614958e71876f91cb59d408dc8c81a75c361e3d034368771c69bfeb9235fa0

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2-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.2-cp314-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for cosalette-0.5.2-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 235d95ed4e929b224d7e36ffe3c62d91b51f3b60a40383d8be80f78c456af99a
MD5 93f8b9a6fb33aac28cd2ef508c48326e
BLAKE2b-256 2e5ee67582957d50dd6be14116c0c45db106c07b1b5ba5a05521bd9c15e87e52

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosalette-0.5.2-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

0.5.6

9 files

0.5.5

9 files

0.5.4

9 files

0.5.3

9 files

This release

0.5.2 This release

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