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 18, 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 18, 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.4.tar.gz (379.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.5.4-cp314-abi3-win_amd64.whl (590.5 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.4-cp314-abi3-musllinux_1_2_x86_64.whl (934.0 kB view details)

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

cosalette-0.5.4-cp314-abi3-musllinux_1_2_aarch64.whl (901.8 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.4-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (731.1 kB view details)

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

cosalette-0.5.4-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (733.8 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.4-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (726.4 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.4-cp314-abi3-macosx_11_0_arm64.whl (696.2 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.4-cp314-abi3-macosx_10_12_x86_64.whl (698.6 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.4.tar.gz
  • Upload date:
  • Size: 379.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.5.4.tar.gz
Algorithm Hash digest
SHA256 b672b6b7cc020d258374fcc137504bb6520e6e845f38e50b78b9cb241d12a98c
MD5 6a9866caaca3f8fe44af2f1decec3eb7
BLAKE2b-256 175d96b675f79683581c456cf6d97e8967efcbb73d36ee4ab32ab7b2bf6871b7

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.4-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 590.5 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.4-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 f79bd1e6f9f88fc8004cbb7ec05c37a270cd4aa445696149dc6adf25b58e7567
MD5 0992b348223b3e8d36ea7fcb6cf9c579
BLAKE2b-256 eb7081a7165a51e9ac54647417b57438a9588b54aaef0f82d07483471092aaec

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.4-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 cd262202f2f6ad8dbc1b25aaba8f05baa85d387902d986843204ca574050a18e
MD5 fc3361a23eba274e1b583f005d0c10e6
BLAKE2b-256 b5cd968483765bcbda0da929a16f3e40dab578be94bb64616d7e7e76dca69ca7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.4-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 53bace72fc92735a9a6c3892d95bc5eaaead726113264c2a65ec1a5e921cae23
MD5 79c55bf1d01dd5fddc5c9df65a1c7f05
BLAKE2b-256 7cfda41267fea5a76f0a3487267bc0473bf6bb49c9029489c3ce5f5506cd0407

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.4-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 90e3b13d1e39d97df40d88e04b7f88f84714a9df217c9df8248eb505ec47f6c1
MD5 8096645245d20b9596a1c4954710b8a3
BLAKE2b-256 33a937a583a51afed59838198577755ea5f1ad7edbbdb1cecc0ac227e5ebca28

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.4-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 c9654daad02a0b75de15d27b4deeee70c2780f08e983a9629d9b0cddc0e70c93
MD5 47629da3cb191da0d00abc11b9cdba11
BLAKE2b-256 52a466813bcce933c16c46a5bf15e882412f96b47df0ba5755e41f321bfe564c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.4-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 2d50432507110caba2a9dfde6299fe5c34a34b8503516b6534a593c71f13d071
MD5 99a9037056dc6b330a826498d2e83264
BLAKE2b-256 f4e600269af4fcffd87729c77dbcf7b0a9640c16fc2aeddecfc0518e9c336be7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.4-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c556f22212cc350157439e6ae313cff73e698897309ee6f6b12011ef66d894e1
MD5 31b94b5ecf01f991c29421bd4aa0a290
BLAKE2b-256 2360c006debd2f467d1fb9061b1c0e77b4d62b18745def6769ede50b5db75bcc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.4-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 ddbb1a0e1c106bb29b55304007b886dcf3cbbbb231203ae5367f61fa464fb6d0
MD5 81f947489c013e891cccd381054097e6
BLAKE2b-256 c5e7b0bc4b74691ebf7e90cab4177b67807d29052e5d72427e747936d184a9f9

See more details on using hashes here.

Provenance

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

This release

0.5.4 This release

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