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 27, 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 27, 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.8.tar.gz (401.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.8-cp314-abi3-win_amd64.whl (614.0 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.8-cp314-abi3-musllinux_1_2_x86_64.whl (957.5 kB view details)

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

cosalette-0.5.8-cp314-abi3-musllinux_1_2_aarch64.whl (925.3 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.8-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (754.7 kB view details)

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

cosalette-0.5.8-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (757.4 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.8-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (749.9 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.8-cp314-abi3-macosx_11_0_arm64.whl (719.9 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.8-cp314-abi3-macosx_10_12_x86_64.whl (722.2 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.8.tar.gz
  • Upload date:
  • Size: 401.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.8.tar.gz
Algorithm Hash digest
SHA256 4cecac415f85cd6bfb3711b05e7674880720546ea61fa88ed87d266b53eeb0f0
MD5 a7d25f4c78b6b212f07b92eeab9dca2e
BLAKE2b-256 0c682608f03d1f6e4c3672454f457f79780d3b26cbdf5d57ed6ee90157a60774

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.8-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 614.0 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.8-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 82e6c69f2d51d3e0a763f58c866f63fbcba3e03c451079d67060ddbc66d4f293
MD5 fc66f2609feecce68c45136d168dbba9
BLAKE2b-256 39f2b12eefd95197dc5b3065993a64f8b1e282e3dc73208d83a6b9a4363c9492

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.8-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 31692d43a796bda6c3cea44cfb0a6d811334ebf3ad5f0c3933a9bfa72167f19c
MD5 1336fbbdae48b96da0101821cd8918c1
BLAKE2b-256 7822cc92518fa015517e356549ef4d11869f0f85f27b482652e80b6b83c47e32

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.8-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 812ebd7ec5c95160f00560e61ac0a14b1d71a4a9946225fb76e9ca7b71ce107a
MD5 81a7dc9ae964c6d38b12ff124b8e57da
BLAKE2b-256 bd5608acfd9c1dc4a9cdaac300426d174c56a1ecec2c69e307c469aa6334c47c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.8-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3e928fa117e534f186e377c0ede5b5d60cb87fe1d71cefd4b30bd6114b4df28a
MD5 1c9a93cecba57853e9e6eff7e845cce4
BLAKE2b-256 bea6a600ad0eba2521d099046282d0d9b5d028fa7a22da23ad779aba5bbfc3f6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.8-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 9d537db1c6ad3777a1b5f3554d73bdc16b752679072a0331092c558dfd153b16
MD5 9248313e7686a7ac02aecf5c62db3a33
BLAKE2b-256 ab098c5ba0576cb4a6b7fa3619f0332dde2b47393dad86c7c3fe92a4c269b5e4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.8-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 5b5f076e2cc795555d5ff9b77eafed8810a5d60539aca0cf83dc118e96a2b452
MD5 6944fe97da00c6781cb31c75dbe53c0c
BLAKE2b-256 cb03511730819836cb68d7707672f58526563c4507b7ec3380c9d72b824f033b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.8-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e6f6ebe27f10ef5d53a13ad4931b679e49ab809b900e7d6ddda7a7927c48e8e0
MD5 9445f51144de487d3a70a61de5a10f6c
BLAKE2b-256 c9d1ba81e9b645ca69f4392b84e21fae028988327082c2d3cf7cfc0aeba3239d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.8-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 04923ad46349d99857063bd124519a189dee2e9b5248b9a5f47f5063d08fd746
MD5 de0781bf2f0a79709b46726c22f47a88
BLAKE2b-256 5862b13487a9b295ecfb68ce3487b257e973bb258e6cb771c67ef1f8832d0477

See more details on using hashes here.

Provenance

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

This release

0.5.8 This release

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