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 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 Aug 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

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.2.tar.gz (498.4 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.2-cp314-abi3-win_amd64.whl (713.4 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.6.2-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.2-cp314-abi3-musllinux_1_2_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.6.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (854.1 kB view details)

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

cosalette-0.6.2-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (856.8 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.6.2-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (849.3 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.6.2-cp314-abi3-macosx_11_0_arm64.whl (819.3 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.6.2-cp314-abi3-macosx_10_12_x86_64.whl (821.6 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.6.2.tar.gz
  • Upload date:
  • Size: 498.4 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.2.tar.gz
Algorithm Hash digest
SHA256 2b03de7318254bb9b5f98c7c6798e3e89b1027f2142161a193f7a04ec902677b
MD5 374a3e2cdb8d317d9630d13ccb7866a5
BLAKE2b-256 18f0032c76a5c2cae4f818939b586ec99d1f3ba02c43242dac81af6079b55ef3

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.6.2-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 713.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.2-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4143dcf4b76e8d620f2865d11c7a02eecfc357c5bb9cba6b6b4a0b7d21e5d6df
MD5 0aefe9ef809dd79268cf87b035537b4e
BLAKE2b-256 16f8fefeafde7f372f7c35b9fb1ba4e307adb404a31803262cf9fce21bb68583

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.2-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 0fc75d6f9915dc2fa2d9c21c56563e9e7f01423c5f6aa2cb798600bc492439d3
MD5 4396bea26bd05e1923d2516972c222d9
BLAKE2b-256 31ec2b2ad17d5f31786cf984fb43e3a503c05ca4faf0516736132e700aee9750

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.2-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 81c0fc197b9cc1ce7cceb041611605806ecd7556033515104c90523b8296f5ee
MD5 285eb0ab2e8f56b1fc02bf365b0ba4b9
BLAKE2b-256 456d7d34cdc4717db6202b62353ce1e5fa1cf43c3e73a651e465e430b996b17b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.2-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b6ad187a342741a4743325adcc6914f49eacfdb4e1a093a6165652f5a4538cf9
MD5 710ab4cb9eec2a91dd419c740d7f30d8
BLAKE2b-256 809d924ba4ee3b0539262d2931cd2c3f8b3f506b6e23900be435020ccaf0af0c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.2-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 49ea754d1e55144c7f16ec7d59868cf85b51ab45e9c867056976e26fd5cfe52e
MD5 2ebe6e895ed8946caab5a47027fb106b
BLAKE2b-256 04f7df3c97bde35003ad0815395dfea35ad3964eb2b46e8ee40274cb3493fb65

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.2-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 15e8c872a17c6eba8d2a9567639b3d235e869c4b15da43176c8e0c68634c9373
MD5 4bc8a967968736e5720498fdce6cb184
BLAKE2b-256 cb4a74d8f2010a67c53debc3e3be5b2e70c34a0caa7cdad163ca3e9494fafa6e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.2-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6a1cd09b93af22f83f8447e81403d8bddd3266b795df38f649a1512633998c96
MD5 df2860a0d7ce05099214c71c0e1f56b9
BLAKE2b-256 498b95243e7549639473711126becbcf8374d3b87bd530cbdd032393b1af8e35

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.6.2-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 45407083bd99c8b7eb40e5110f66d42ce94c56449199711bf1037b5d5b5eae25
MD5 b283412e94e00e724d437b5f0e30da37
BLAKE2b-256 dd9ca2b5db01cf610eaafed97d85edfc0618232729903fc79f8e91318678b8e4

See more details on using hashes here.

Provenance

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

This release

0.6.2 This release

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