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 2, 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 2, 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.9.tar.gz (407.2 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.9-cp314-abi3-win_amd64.whl (619.2 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.9-cp314-abi3-musllinux_1_2_x86_64.whl (962.7 kB view details)

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

cosalette-0.5.9-cp314-abi3-musllinux_1_2_aarch64.whl (930.5 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.9-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (759.9 kB view details)

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

cosalette-0.5.9-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (762.6 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.9-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (755.1 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.9-cp314-abi3-macosx_11_0_arm64.whl (725.1 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.9-cp314-abi3-macosx_10_12_x86_64.whl (727.4 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.9.tar.gz
  • Upload date:
  • Size: 407.2 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.9.tar.gz
Algorithm Hash digest
SHA256 868aa2a2a349fd7947bc9ff4d5ade9970cb47babc0d7189fb87d334b8ea00114
MD5 3e9c843a10c2da029bed3579671943bd
BLAKE2b-256 5434470c22c94aad720e23641e266664fe24980f0a2086f91515d83150da1cc9

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.9-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 619.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.9-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 7abc84403732d3011d95943efe93bb993fd24ff4b358c6e0bba34401d01adb64
MD5 d920a9cb63ac6ba2b409f050c5920d07
BLAKE2b-256 0e8a632456bfe84c3bc8c3f27c0a1336e74306378a5bec32e98775b4cdc06464

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.9-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 f8d417ce0e87670fee5a9ec35b577fd01e323d6d13973c8540933e802bc1084e
MD5 b9bd51fd99c9f5e574741fbecf0dac27
BLAKE2b-256 2f86ab8f47deb9a1501aae20d6532c48b1a59bf8f7da80f00c1f85354d0f00e6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.9-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 6947b4d9323be07e0ce7bfbfdf1d12b7d410f5064d37cfaceb7b58bd20ac8bfe
MD5 a87d1fe79c09d3f33eedeb348980f349
BLAKE2b-256 14d4ecdc1199b52e6117f75a5812f7ca7f32672e5675eda771a405dd3c0fca18

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.9-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e875870c10e1494fa3f41dd3a75b8b6e978db1d1c3a68d9b9f81d6444430941e
MD5 2491b0890a1bc0e75936f3068d126144
BLAKE2b-256 928f0c26b8629cf854fad07169f021f513f50c7948957fe8c6ca8415ea36af4c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.9-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 2726de0f62ed8c9910cc6c37e01b20451d8771fc92e37bdc7509b434ff98ae00
MD5 b70359b4e6a01280b7da2a62084d3e62
BLAKE2b-256 009d76695ad24e05424318c0bb4dcff4feb9fc75930bfa75cf027fd343c6b0b7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.9-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8983e909eb7b42efff78477ef5583ddc979e09252d279a44e952af5e39963ef4
MD5 3c5793b21ad6f3204f8dc89311b3a288
BLAKE2b-256 bb8c112f16a1812ff23303443ff881b81c88bd82c4910e12f820ec5be2f068bc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.9-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 53a11c12256b30716ee8ba5ab0421b69449ffaf89aa45eb12dfb88d87968ae48
MD5 c1a67223c1509f0a7a020f4f7ed84724
BLAKE2b-256 68c415189d1dbe9d435c2b6fe90ac366786ea01823689808df3111827077b7cc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.9-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 61a9e21a675dfda15656dc8bd624171f371d38db240214090320c0aa7e124acf
MD5 723fc4348c4df2afb3e9f1e27cdf7232
BLAKE2b-256 eafd7cf501272e0bb2770b40ab8f53d734ed7599c3e259ffd23aa25558ae18b3

See more details on using hashes here.

Provenance

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

This release

0.5.9 This release

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