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 11, 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 11, 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.1.tar.gz (460.7 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.1-cp314-abi3-win_amd64.whl (673.9 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.6.1-cp314-abi3-musllinux_1_2_x86_64.whl (1.0 MB view details)

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

cosalette-0.6.1-cp314-abi3-musllinux_1_2_aarch64.whl (986.6 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.6.1-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (814.6 kB view details)

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

cosalette-0.6.1-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (817.3 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.6.1-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (809.8 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.6.1-cp314-abi3-macosx_11_0_arm64.whl (779.8 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.6.1-cp314-abi3-macosx_10_12_x86_64.whl (782.0 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.6.1.tar.gz
  • Upload date:
  • Size: 460.7 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.1.tar.gz
Algorithm Hash digest
SHA256 07e1f929e8fdf552f0aa1f3323c8e22406bb0bb3279c389a72470991e93aafe9
MD5 66df05c5897b05fad0f97f6f1db44220
BLAKE2b-256 9da44b6676533a8f65e7ea8d97e7fe0cbff4083cf2a74ab9bd2701d80c5d4d08

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.6.1-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 673.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.6.1-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 5702705accac924214f7ed22f4219e457ba83648ca0416a08016b18a87e96c41
MD5 c59bfb98b0948277721cad8500c02133
BLAKE2b-256 64b160558f084f96ba024693acf8f78b8f4c8dfafab04bd6384da660bf9bae50

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.1-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 abe2582d3dd5f24dd9338e875ed454426779c23c9815705dd62261695cf9eb81
MD5 a16e235833601a3763bd4c0abdfab353
BLAKE2b-256 9a6196ef5989cab44f9a6784e855e703f6a0a0b0d23aa83c1a54efce0dd036a3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.1-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 59147c13ab077c34506df56046c0267e1a8c62dc0d2944b6ff9da085a127fddd
MD5 aab73ef62206780051cf7751130719b0
BLAKE2b-256 90632b9f7ca767d4eb67fac6414b5d1a3ad804558991f4a2ca20fac7ba5f132f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.1-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 34432c130becbea76f7e43efbeaa34c544ed133e12e15ad94ff10eaefb5dffa0
MD5 f91316dd75054d5a0a6efd999a3b3bb0
BLAKE2b-256 3cbdbdeba301734213509ae27c9e61dcda774b99d2e5f53d5f404e0efd053858

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.1-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 524a35455356dde9da134c61c48f60ca4748b5156dc7607bfeaadfe9c4969926
MD5 d292bd5ae2d19e7c0caec215b1b33c39
BLAKE2b-256 5f60c558a8ea68e8cd32d5884e6d84badde4ded8a50f1e0efcde91bc069938b0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.1-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 abd873ea626206b1a8a5fdd0d80b3cc0d3fddb552c3ada992160467b4e1b83c4
MD5 63df9c3f0e7d43f790e5324479c6352d
BLAKE2b-256 451af9f05fc8c92df8a000eb0e82b905b1927bec6906114d46c57c729851b7f6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.1-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2ffe1ab95f3f16b1831ffecbd154a7c832c82ed52ad1ada80fcd5777ac31208b
MD5 e2d329148908256d63e5da085415bd73
BLAKE2b-256 661683b841f798eea89b2cb4bc1f2e6cd3352ce8a25927f6167fe8332e55bd91

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.1-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 0396fdb4d6d9c5a68e070ab20039bafaa3d1f6a166cee0f067658dc0a17e779b
MD5 bcec1304b79cee564c85a10b6270b986
BLAKE2b-256 abc6c64fb30746ebe122c26e673652e43eeeae2453e16ebf8ec35d2e62b8c3d0

See more details on using hashes here.

Provenance

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

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

This release

0.6.1 This release

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