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 24, 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 24, 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.7.tar.gz (397.9 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.7-cp314-abi3-win_amd64.whl (609.5 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.7-cp314-abi3-musllinux_1_2_x86_64.whl (953.0 kB view details)

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

cosalette-0.5.7-cp314-abi3-musllinux_1_2_aarch64.whl (920.8 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.7-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (750.2 kB view details)

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

cosalette-0.5.7-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (752.9 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.7-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (745.4 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.7-cp314-abi3-macosx_11_0_arm64.whl (715.4 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.7-cp314-abi3-macosx_10_12_x86_64.whl (717.7 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.7.tar.gz
  • Upload date:
  • Size: 397.9 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.7.tar.gz
Algorithm Hash digest
SHA256 30259b01b16f705ec3a8105c44ffc0899dcc432a3e18d23baf0b9c476813e08b
MD5 ce9e43f0a56ad923cc7f8c8c1c00d806
BLAKE2b-256 007c7ba75ef65985c5588cdebf64da3651c48764007cf3b2bf402270f7d84ff7

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.7-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 609.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.7-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 aee67bee2010792c25aedfde068ff451ab6d8dcdf8449f95ce55ce25fe6c47ba
MD5 323e9b60cb60c95cb7099bfbf9df74be
BLAKE2b-256 548c40d1e9c779184f401786ed2f168e95db765eb64f3b9eade94239bdcc35a2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.7-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 289b8d401df7cff9689854cd5d9ccd61f5be4abcae075b7a82d0ac77ba2f576d
MD5 584ee603e5d874d61b24244158d7a566
BLAKE2b-256 855d326416332df3b3fe9e7199cef75ba2ef53a000cdfbc86d7a5c5dac4bf62c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.7-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 a1653538c1efa8efbb925fafb39d337731a8c3b07986692dc9efc27daa2208f2
MD5 0a7c0f8919f2a26bc395c42884c9b921
BLAKE2b-256 d5902f268934eaa185f9f35f2126146a0bd7f96e3489bded0a2e86e836ae71f5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.7-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e793aff3ade7cd3b763956078fc5c664d205fa69cf4458dfc411d67484842a6b
MD5 95515374191d1ec15027949cd8db859b
BLAKE2b-256 af8d55006420f80635de172f63d6d88b0e1f860276daa5c4c355142ba82b39a2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.7-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 2d46d3ced31bfc68a923666a57ef93fe308fb60893b99649292f2224209a7e4a
MD5 f140412f39baa4ba33c93f630b916eaa
BLAKE2b-256 d237a11da5eda0ffca1d54ba5598193b31986eca664fa5f05636b0151b68000f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.7-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 adb14ff84b200c27926af4537084e36bc6cee17abc71cdffaadfe1bb1b3b4d33
MD5 7fa4948158fb22e8d5130f3b3cfbb6a4
BLAKE2b-256 34941324f23a9bc755fd49c2e0e9b468df32c4be7bef14157ba9aaddc88eb1cd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.7-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 03bd3abed8d1c997de874a9490a12334ac7271b356b36a137c6e120a674e532e
MD5 002608449e32ad51945e01867392ba17
BLAKE2b-256 30ffbc0a49c8d12020e9c7d4b941c3132d633430755415f680af7559a56b4859

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.7-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 989970714f6f45c918332c163a8f7d8b5fb4598771e6147743569e242e86380b
MD5 5ab8b2b74b811ecef51a9f82b487eeab
BLAKE2b-256 10f52a9fd317222471044b1e0542bc117af7a79f9de042b5ade75845a8098056

See more details on using hashes here.

Provenance

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

This release

0.5.7 This release

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