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 Aug 22, 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 Aug 22, 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.6.3.tar.gz (500.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.6.3-cp314-abi3-win_amd64.whl (715.2 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.6.3-cp314-abi3-musllinux_1_2_x86_64.whl (1.1 MB view details)

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

cosalette-0.6.3-cp314-abi3-musllinux_1_2_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.6.3-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (859.1 kB view details)

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

cosalette-0.6.3-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (860.1 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.6.3-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (852.7 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.6.3-cp314-abi3-macosx_11_0_arm64.whl (821.1 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.6.3-cp314-abi3-macosx_10_12_x86_64.whl (823.3 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.6.3.tar.gz
  • Upload date:
  • Size: 500.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.6.3.tar.gz
Algorithm Hash digest
SHA256 080acb9df4aad1a7abab313f5d80f9706779fffa50b4571a0e3318eea74cb015
MD5 916e1ecb8218a5e1580b74cb00ba8188
BLAKE2b-256 b988056bf7ec9bc1c1516cf4a76622b20386bffeda1ef987c1bd5658c5e0c533

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.6.3-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 715.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.6.3-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 0b94067fc76b360b23d4a512a751cc0b12c337b8865c4def14556d8b9e096dfd
MD5 ada7d6d73855e10837670cbd8b72bc11
BLAKE2b-256 d840f04cb893c7e8f5c56a90c29679cb4f22bb288e6c26a9a3a3a1287b942f01

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.3-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 4acf50e18fdf91e6d9b748ccaf92c8f51a7e60695741820ff44c540d72cf8dda
MD5 8cf3fcc81b52876876d19f05792426ed
BLAKE2b-256 8d2bd94fda20c95e519f0234f4c70f4adb371635d2d735997e16f3137b6e792b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.3-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 fea89598c4232643079b6e936f77cd42708a71abac747ae1092448825fe21471
MD5 176f9690bca0105f7b2c37bfb6bb3b72
BLAKE2b-256 ad5d366e78e9d7d32daf9d77e0235dbcece50b7e6c20c5824d3a79faf5f455fe

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.3-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7fb10f8e082a6facd4b4fa208d8be378d10a2fccd7d6c96e65961b072411f116
MD5 55e4f10b642bbb749de1e15845760817
BLAKE2b-256 886878c2a6d3db9283c327f2f90a06ec228ebc5a4a7bb9ccdc3c2a50b359ca9e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.3-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 64b68ca8889379cfa13a3d340c9cdc5c80ff72e8e083f9b2425a70019a201b88
MD5 1c62b9594ad9efc8476e3f231127cf0e
BLAKE2b-256 e1ecd3db8a9825500984dadb46b8ad06d76c0d33de844b3e2ad4308de534d13c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.3-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 d91156ddfd38464cf09d6394ed06e087f282dd13f78795154f7329dd297846de
MD5 7135826cea6ea4bdc80be43b9dfabb3c
BLAKE2b-256 86bf127b6abc77231af0c05cab3ddaba3abfc838b500403dd01ba676c8eeb058

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.3-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7b821116ce845c12275d34b94a7e69196d68b3d8d620f42c804ef4bd5153e7c9
MD5 8144e8f811ff2d3681b5c18014580e50
BLAKE2b-256 36ce64600167bbca025f5fdb73d66c25c4a6920a35e92491bb2c732040c82f31

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.3-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 2ad2e019bedf959a63d87967975db626bbf20af86903312c7fd3df80ec6ce4e2
MD5 03e2d4a79f513a144aa6691b2e06f810
BLAKE2b-256 d2fbf66cf50675fd60eea3575efe8909a8bfe1e1b29866b5c78f77c9b1f24414

See more details on using hashes here.

Provenance

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

This release

0.6.3 This release

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