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 Sep 5, 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 Sep 5, 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.9.0.tar.gz (619.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.9.0-cp314-abi3-win_amd64.whl (840.4 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.9.0-cp314-abi3-musllinux_1_2_x86_64.whl (1.2 MB view details)

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

cosalette-0.9.0-cp314-abi3-musllinux_1_2_aarch64.whl (1.2 MB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.9.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (982.8 kB view details)

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

cosalette-0.9.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (984.0 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.9.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (977.1 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.9.0-cp314-abi3-macosx_11_0_arm64.whl (943.2 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.9.0-cp314-abi3-macosx_10_12_x86_64.whl (945.4 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.9.0.tar.gz
  • Upload date:
  • Size: 619.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.9.0.tar.gz
Algorithm Hash digest
SHA256 2fda9c836ecdbfcadfb29065391ede123596c5d9c94066d8c29193408dfcaa37
MD5 11e5ff7f65d77b7bdac6701998402f87
BLAKE2b-256 d3523a8ba289d3da47bd73a52d1b1b50e2598d475b17de40871dae3fe82ccc3f

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.9.0-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 840.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.9.0-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 485a2e5d8484401f638e36f2c0798c2b53edaf9dfc7ad2d0238e2a18fa4ffa81
MD5 d06ec3253c8fe8c00678a75d7c1f8e4d
BLAKE2b-256 22d79fb9c8b1df3c8b6d3db9a76f0b7e38c5b8e7262a8b3f45bb3d8739f0e475

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.0-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 629d1a04771c23c5be77075f6b1045b789ab6c32390927659ae69070624a75fc
MD5 fd2905fd3640a24a76841ce449dc853e
BLAKE2b-256 5f08dbd90835232e4d9800513c0fb8fcace97658ef1eb290d5fc1965a68e9c70

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.0-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 7446af7fa7199ff44aca5aa1215f134acc5af2cf0879359a8ce24e53153658a0
MD5 da74c941114e39c804f9bb1bb8e1c98e
BLAKE2b-256 1aa5f149c45ed7ea09ea02d14211fe3bea27c9868a0c31029c7e7e0c8a2385be

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d9e4ca8f98422113b9c842013f4ca5be1a72a29e7a60f6b7647efde5719463b9
MD5 11c6fe21af79a6191eabffc27b1d1779
BLAKE2b-256 7cd40989313ae7ca4af9f9e8da18cacdcdd5cdb812025c3c09778859087fa300

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 04dbb9aaa9df810a99598f6dfce01d6e54ec573199cdd407ce3053a7d1146f4d
MD5 360a2c154cf1f1ced803c0ba6f8c6a9a
BLAKE2b-256 38df0da52ac970c42957db824bba46dd1523f9fd29a080f46efcaca4d7f7755d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 46eb95a1cb03098f101dd667cb7d42d5f49b313ea9599d19ff3837c7c6ec0a94
MD5 30bfb135f6e34c0ee70642289384cc64
BLAKE2b-256 c06a5db6d29465e359705c4e53656107b381cfb56bf3c176008b8f9762ed0a9c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.0-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 34a45ed70b9d6ff15dc29d3f8dada1e9c8202ec5b16ed6db284b1349f190fea6
MD5 22d1892ff895a36b3817dd71739bf2bb
BLAKE2b-256 7456c1630ccd2be0d8e15dae8e5c545ff7c4190898e96bb6fed6c7d756e66101

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.9.0-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 136f7c19c366ddcf4763f4d2f4df2051a3a6f78dc9cd8031fac8f275ec9a38bf
MD5 a2f96e85f63700377083832db5616f64
BLAKE2b-256 79b6366c7e23978fa52f7a5ae67f2fd972cd92392d56889aec3ee624102c859d

See more details on using hashes here.

Provenance

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

This release

0.9.0 This release

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

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