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.5.tar.gz (380.3 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.5-cp314-abi3-win_amd64.whl (591.1 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.5-cp314-abi3-musllinux_1_2_x86_64.whl (934.6 kB view details)

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

cosalette-0.5.5-cp314-abi3-musllinux_1_2_aarch64.whl (902.4 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.5-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (731.7 kB view details)

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

cosalette-0.5.5-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (734.4 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.5-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (727.0 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.5-cp314-abi3-macosx_11_0_arm64.whl (696.8 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.5-cp314-abi3-macosx_10_12_x86_64.whl (699.2 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.5.tar.gz
  • Upload date:
  • Size: 380.3 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.5.tar.gz
Algorithm Hash digest
SHA256 0ef8abb861a6f2f9cfc3a741be42ca32330439b5cc8256570a0d886a1e6ff950
MD5 7b831602ac0a0826b2bcd719779b1560
BLAKE2b-256 993d765bce37ce463d330ab91ee681e5730c4c2f6622c119bdcfb9a1c2ee1458

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.5-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 591.1 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.5-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 28e935adf33bb4e67850a42e657012bfabe11cb571d4f65fd18e719465ac05ca
MD5 8416ed2aa7e3331134a33a0909184ea3
BLAKE2b-256 d1e3de9bbe76e43bf96d360b9008b47625d958e99241319ae247b8a85785370a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.5-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 a5cd73dffa4b11f36630e37fd43c02f5673bc8d77c21f99c023cba596e20d415
MD5 6329385515ff50fd5239f76302e81117
BLAKE2b-256 119d3c1c543d1669898774cde882ec0e1e7e04c3033b4cdb012fb72cfba9ba99

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.5-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 1d3e252104f9520f8fcd324ba7ccb7baf7f8903ef1b8cc5cc6beb271732d48dc
MD5 52db9369f817967b92f2d28e9a9cce3e
BLAKE2b-256 e1040bcf9c97ad6b5060617399646d50eee7ddc2299251b9e87ae1ad038b4f58

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.5-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0eb3b39ffa7cfdb6f2b2888f76b006101a373b2ec3ab3184882d6dc44cf26c87
MD5 0caf9749cfd4f7da3a45593638049e76
BLAKE2b-256 327510910bb89530681f1acf233aa7de0ae41eddb41a8aced58d9ed221538256

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.5-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 2bc59e9bbe4ab4dcad106e54bb414e1f711b0c35fdfe3edec6c6d4245d6d09b5
MD5 b869a67907cb88dcecb121aaf1bef108
BLAKE2b-256 b2476c896850b23067c55d59010ee05fa7cfb8865449f77f431747c05c9d59e9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.5-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 c44023e4010abcd8db9f75fad654d138f1cacd7d727fdd6e7f4846c194c0b246
MD5 8f4129b7197f9558dd5e2acdd9d3ac1b
BLAKE2b-256 020b8441992f28b701c9a419ce5f582f5c85347a8156820e21c750c85f1c7b6e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.5-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a57bc68216acdc9ac645f696c5ec0d002cbe62aa2352c3cb9ff7ea98c090d5d1
MD5 e408315c6b1cf30772663dd592991ba0
BLAKE2b-256 5e24e45eb4bed524ad3f902d20575abf8b96b636834b165c95aca76bd4f8100c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.5-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 8ac0bcfa23f900f41a3b8d4cf19d3c36ddafecba71e866f9e771171d78a63804
MD5 6fbbce96c94f33cd3e1111b21927cd19
BLAKE2b-256 40b6210a6b5c8b2bb05b40f78dbb2fb90b7c4b5e918a5abb4b900a1beaaeebda

See more details on using hashes here.

Provenance

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

This release

0.5.5 This release

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