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 13, 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 13, 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.1.tar.gz (374.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.1-cp314-abi3-win_amd64.whl (585.2 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.1-cp314-abi3-musllinux_1_2_x86_64.whl (928.7 kB view details)

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

cosalette-0.5.1-cp314-abi3-musllinux_1_2_aarch64.whl (896.7 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.1-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (725.7 kB view details)

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

cosalette-0.5.1-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (728.7 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.1-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (721.2 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.1-cp314-abi3-macosx_11_0_arm64.whl (690.9 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.1-cp314-abi3-macosx_10_12_x86_64.whl (693.3 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.1.tar.gz
  • Upload date:
  • Size: 374.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.1.tar.gz
Algorithm Hash digest
SHA256 951b3d0620fa317ca5f1d4a4efce0600d7f0a988ff76a6f8932df9ee20c1c17f
MD5 b3c6857b8446039cf9a28af4a468141a
BLAKE2b-256 dc5374065325ac9b7c9df7beeaac0f1425f18345096237c32b0e8e34631470eb

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.1-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 585.2 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.1-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 b6a9d10803dd6e9021aec82880141af2af7a24b9b98c68959eebcb0a5d4f48fb
MD5 ebddfe8de2e8ff0e8e6bbf0da177e38c
BLAKE2b-256 e158697046206304a9c4d9bfd496613863adb07630928bba7a330ba18f98d944

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.1-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 db09eb7f979d898dbb0021c3d23bc6badb29826cccd3eb73394a0ffbff1f912c
MD5 0ab8e63ad01fdcf5859e95eaefa29635
BLAKE2b-256 91175a6488205e16748ccfb258e02c3575333c948e243bf3888e39cb8559f639

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.1-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 16cbc2d335de7530f9a927260bfe8c718b1d573bc1ec9fe5edffe53577d87b6f
MD5 9724a2827d613f17f13b112a485d4ba1
BLAKE2b-256 cfbed224c0a5bc524bdd97ae04f98dd5b9d9004258d6464ca3dda305a4ab500c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.1-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2a128dbacdd8c5e8bd8b94e46e296fbf314ff52e2b18ee5e34b2b30a43f1914d
MD5 270edc504d5e7be596c735ae92680a0a
BLAKE2b-256 ce70935982e8589fddc4a938f2df727bdfd755049eac8edb63ef16ddd09fe5ff

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.1-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 5a307eaf121d0670cc6e00eca0fde6b825da86104e1b3f67501f4c931be348f5
MD5 153b82d4e96a7f319b81faca2a332d16
BLAKE2b-256 b8a51c25d751afe31580b7b17be7f19e832db2a50755160f111ec2501dcd9366

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.1-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 2686ad13c1101decf6ef16d8ae074ebb91776a35b1c8a98a360bf1c89b9847e3
MD5 7579f3cb4daa40634264640c34861072
BLAKE2b-256 93fa4f807c3ceef67b36309ccb43739d7522a643256de173abfa2e32601d454c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.1-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 43b804139a1793ecb402a8a09fde33a86a4eb7faab07dd2035601993435d7bf2
MD5 71869de730a4c4d5ddbf24f78ad0e643
BLAKE2b-256 7760fc7a3a17faaeda0614680fda0378537f978f14e23ffc579bfaffe7427628

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.1-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 c82889cedd232db6d9e860ad14613f1fd7ee8ab54b0c9f353d601d173fa751b7
MD5 b508099594a024c70cdd8e2f099612a7
BLAKE2b-256 66d4c46ea640dc2b1865bb7d9352977693a565540539d636d7cdcc21ac3fc76c

See more details on using hashes here.

Provenance

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

0.5.4

9 files

0.5.3

9 files

0.5.2

9 files

This release

0.5.1 This release

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