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 Sep 5, 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:
Latest release

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 Sep 5, 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

config-yaml 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.9.1.tar.gz (620.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.9.1-cp314-abi3-win_amd64.whl (841.1 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.9.1-cp314-abi3-musllinux_1_2_x86_64.whl (1.2 MB view details)

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

cosalette-0.9.1-cp314-abi3-musllinux_1_2_aarch64.whl (1.2 MB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.9.1-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (983.5 kB view details)

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

cosalette-0.9.1-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (984.6 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.9.1-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (977.7 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.9.1-cp314-abi3-macosx_11_0_arm64.whl (943.8 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.9.1-cp314-abi3-macosx_10_12_x86_64.whl (946.1 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.9.1.tar.gz
  • Upload date:
  • Size: 620.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.9.1.tar.gz
Algorithm Hash digest
SHA256 d9e943ad40844d1815243842015104232d1f5fc8d8af49cef611690e603989f5
MD5 ae40a685796a7902f2ff05d89a4478f8
BLAKE2b-256 a7ba8f0d3e51c581455a3da8abec22d270daeef57b7b096e598d2a14bab544f7

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.9.1-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 841.1 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.9.1-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 cc8e6370025d9266d8ef4e9ca59b018d61ca09110a6ee38533f4e5db9c459549
MD5 bc12dbd8d26946dd057e244ae856b108
BLAKE2b-256 fe4d9b4d62f4460118d207c90af8ecc6c69d84c9116d4c80e1714e71d054c0be

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.1-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 ea8111b1bcbfc15125c65e4e049ab363461e2922d5a219de1fd0a9cc287746a6
MD5 d1639f1509a0e3132cd94ac2df6cb2e3
BLAKE2b-256 f3d6bb9828d1136769cc7024fbe4705d46890eb443dfbb59306c557ab246220f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.1-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 7c088d02ddff7ca6eb53f9e08ad197a7e426af42b3fb9bdf15d3b105de6c59c7
MD5 315152b31b87e7d66d7f6df2b0a63ca1
BLAKE2b-256 ec57f261b89e623ec14d671eceb3a1d84c5d07f16a584e2b3ebd6fbab26d93ab

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.1-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a25ad5c8aab4d3990cd60b65b9442cf6755445de30a56b3215f638f6af8ea6d8
MD5 e2c43a23a00acf725a38f2b192499d7c
BLAKE2b-256 c9cc9489f0de6a436743de8ffb1d7524e378dcacbf66188298bd2269cc7f3fcc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.1-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 86e8cfbf36313d6219707b65aa36554c655b19904b06034b6c0e29f593da4810
MD5 19183667981e3bfd20fc9395176e828c
BLAKE2b-256 d5c97e86cf0fd90561a198e2d463d7e4dfc2b765e138be253b4eb4507aea01a5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.1-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 eafa8d72a411ba49dc3c6eea980e5fcc0164d4433c80316367988524eb810e54
MD5 b3500f845bce98b183c9a6fab6cb9a25
BLAKE2b-256 e2b0c41a43f672b7a1f33076739467eb131768bc339d22959c9b45e490ea4488

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.1-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e801fda31951af3adf7f3248a3555bde6339e6c446c96ffc0a0b68a1b09f7976
MD5 a76af002f018c085dcab016a8c715e0a
BLAKE2b-256 ada543e979a3ab837532d7f8158d60630ceaa0cf8f479d64c6be511ffd2418a4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.1-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 cf3c5a6d5e58ab4c839729612d32af22f83fde058c2dcc8414d018a63cea8f18
MD5 37f287feba467a5cad167716e7a8f879
BLAKE2b-256 35594298f882e04c834b21180c3fc00ad9b669a95c417a353db0fba74aebb925

See more details on using hashes here.

Provenance

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

This release

0.9.1 This release

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

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