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 8, 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 8, 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.6.0.tar.gz (444.8 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.0-cp314-abi3-win_amd64.whl (656.4 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.6.0-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.0-cp314-abi3-musllinux_1_2_aarch64.whl (969.0 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.6.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (797.1 kB view details)

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

cosalette-0.6.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (799.8 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.6.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (792.3 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.6.0-cp314-abi3-macosx_11_0_arm64.whl (762.3 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.6.0-cp314-abi3-macosx_10_12_x86_64.whl (764.5 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.6.0.tar.gz
  • Upload date:
  • Size: 444.8 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.0.tar.gz
Algorithm Hash digest
SHA256 64714074acfd1213c4b2d53728016dd90db88cadc0a593572dbd2abd3e722b65
MD5 d5185e714cd89d7bd362e7e0c42adcf5
BLAKE2b-256 47d1c9e5800b6775264dfe8977d9b198f55bc20eae6aad6a7a61346c1a7f6046

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.6.0-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 656.4 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.0-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 bc33b9fc2ac97b8f19e6992be24314178b5bd914e681d8b998d58c5dfa10f9a3
MD5 8a93aeb938bd4a2607495dcda8ba0318
BLAKE2b-256 8abde2f2f03dddeb5c5df647530c5f9fcf5fbd82cee1120c0012209b559d9fda

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.0-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 dd70b2efe3447f0d1f3e1c745c6baec38a4bd8fbff93d3099e3241d0ab70d9d2
MD5 f3829ad2a681f829913543d0d5ffee37
BLAKE2b-256 7fe81c2ebd201ced2eb8d00a87e49f96950703fb3f77961412e87cb34dca476f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.0-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 c1dfe2d2cffbd05145a9d75917d4bd89c7119f90c205d1e4c5d3948baae72cd8
MD5 2fb25567a68d950d7d24b092ed5fed2e
BLAKE2b-256 8b5604a9b59e1eeba7c07ab002f613af549c9045b88f0d710b4e78c6f2e6a94b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c4ccc0af4b20dde2652f595738037dbc485b42c26cd8c4ff91a792a8a8039a8f
MD5 aedb107b378d01c754bcee3f111351d1
BLAKE2b-256 3d6c69c4082241516bbe38a14295d5d5b5d88a7c8aeba15087b696b072d3bb69

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 11d9ab95d3047f53e37294a4c32caa1487509f9aeb607830f69d9850a59e626d
MD5 350e889fcf51f8ba13b534280e16512c
BLAKE2b-256 741906a423ff5b94390175c48c3be3b43298e2bf757527eaaf62f44ac40f937a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 467022ac48662b184d1e005f382387372f05728a53305c0e1fa678d03f4902e3
MD5 5b543a32eb7c3d389fa53a43dc2ec3cb
BLAKE2b-256 f1fc67dca01926ae9e010fb79370104e3c66a29aedeb2db63159caeb464f1ace

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.0-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 303ad513d6d318bdc6f98157c11bc227118504f330e1f1809e41f8ed4ee60936
MD5 df4ec2e28b5f6b55a473716a03f57740
BLAKE2b-256 6f99c915710706e59d0e6b2d507f8c5844b59ab3df288b1130b658ed2089e407

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.0-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 a6ab4d604ed81919f44ff695b450af34daac343642cf088b323f2b91633bfb30
MD5 13ddaa4739a5b38659c7d05ff3a3b538
BLAKE2b-256 1c1329a121fa76506a22c0aa824998642ae63b31df4f0d2af0ad629702e0e299

See more details on using hashes here.

Provenance

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

This release

0.6.0 This release

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