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 Jul 12, 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 Jul 12, 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.0.tar.gz (366.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.5.0-cp314-abi3-win_amd64.whl (575.8 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.0-cp314-abi3-musllinux_1_2_x86_64.whl (919.2 kB view details)

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

cosalette-0.5.0-cp314-abi3-musllinux_1_2_aarch64.whl (887.3 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (716.3 kB view details)

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

cosalette-0.5.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (719.3 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (711.8 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.0-cp314-abi3-macosx_11_0_arm64.whl (681.5 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.0-cp314-abi3-macosx_10_12_x86_64.whl (683.9 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.0.tar.gz
  • Upload date:
  • Size: 366.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.5.0.tar.gz
Algorithm Hash digest
SHA256 4f1c4de81f86bc6bb7e349e6db570b8ae23631842d4c6421a711b042fb0854f5
MD5 1c45317e147cf7346176e910f5379c49
BLAKE2b-256 0dfd8590b9e047b22dee0757a278f95155cb6097961e13785c06800f88834e0d

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.0-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 575.8 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.0-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 fba21fb8a52d1a7c916728872f74314869be43072c855d910ce6265ac82717c8
MD5 9d505ea5c1833292012c9dc208f25a67
BLAKE2b-256 11aac2a7c47befb1b94f5721925c153b484d21c04a1edf7cf7db8a2020c593de

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.0-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 d7e6a64f665fc954da48bd1c7fc06ef075caf4ab2bc6e51955048f5d3e2692c3
MD5 b3429a7a67390f2896c7f9cab6e18c2b
BLAKE2b-256 f3e44b023ee652eb5e34fdf7029abc4ea6765d6b7b55f64d7b654a44fb668ca1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.0-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 1b799f48901234bd9e4d00f81e1144e281d5a6561d482e118df26890ed185b83
MD5 aae304f0b65c9adbfee9bd1b7ad44b76
BLAKE2b-256 35847f643546a67a7e82f1265048f4806fcf7d22b24fe34c90da8bec16a5bd15

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fe973aab0fec4dff41ddd98a92b951629b8dc079e436f9b34a6baa1774ce9bda
MD5 9c89c277a96a8620f6410a444c579f50
BLAKE2b-256 46d98dcf2a1cab05437799bad160401cad963def66304ce8c69cdb68df54f669

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 47bc470415238a1d7e9cce2bb8f5a16b81fc7c347cccdd5d8ee8d84b8ff13b63
MD5 06902109ef15ca25e190c74a3ec2d24c
BLAKE2b-256 6e1159516936fa62a36ceb4016259b4aba0ecc1527482dd5a1feaefccdefb14e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 622c3d237b66bf912713f45f6111e8cccac3a755638c5db07b754e63616038b3
MD5 cd869a5c36e1464e24810ee5de2ef634
BLAKE2b-256 f64078b6e9e34a7ebe5d9c72de80537890f67b7914bbef0eda1fee2ec3fe1faa

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.0-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 65b22941f0b281933dab1e80f4385c71ea82941a67f47d2841f64a97a6d4cc59
MD5 5ed5c274eef840c28d6bd8851c6463e3
BLAKE2b-256 420443aea5cde7b9a2e68075bf6001d67187fff810b6cadf3162723b57b75596

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.0-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e17d2008d47e05367975b59201b41b42788758e82fb34c44956420c3aa079fa8
MD5 cf91ab473840e19fa86054b22fdd42dd
BLAKE2b-256 da5ada426b5784dcd6c4065ebd15f321a801c74063ac8d070cc1223e16c11cee

See more details on using hashes here.

Provenance

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

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

This release

0.5.0 This release

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