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 Aug 7, 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 Aug 7, 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.10.tar.gz (419.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.10-cp314-abi3-win_amd64.whl (631.7 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.10-cp314-abi3-musllinux_1_2_x86_64.whl (975.2 kB view details)

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

cosalette-0.5.10-cp314-abi3-musllinux_1_2_aarch64.whl (943.0 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.10-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (772.4 kB view details)

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

cosalette-0.5.10-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (775.1 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.10-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (767.6 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.10-cp314-abi3-macosx_11_0_arm64.whl (737.6 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.10-cp314-abi3-macosx_10_12_x86_64.whl (739.9 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.10.tar.gz
  • Upload date:
  • Size: 419.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.10.tar.gz
Algorithm Hash digest
SHA256 98b2734c070afc25d3fdb5c430a083e9093bd4f6518a2ae54be67f34bf754930
MD5 fff0e7024dc5a68f35055db42932400e
BLAKE2b-256 3cfe1264d5768a1d72ff9d1d7fa72445f35b0cdffab153941963e6bb74a8f5a8

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.10-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 631.7 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.10-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e988056b2c065b33249f4f9212232744d7d8d5db0df16bd4f6db54ab189bc4d1
MD5 8b00d9089c39ded67203dd6488422993
BLAKE2b-256 767a400b59ec04578e88a85e1d6c7c211dbde385ceea2b25f4f6615caf6a7ee1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.10-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 3f582052bab1df6b24a22469854cc6afa19c542c4c52f92c3a1271c77b63c2d5
MD5 dcad07682aba1d185951d2b9f569f84a
BLAKE2b-256 395cd465c27a8ac54d34954e24650af355579d34b25d73b2db2d2f9d01627ea7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.10-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 71b9079693317214c4abc427293a318f00ad84eaa5d0bdd04d975972a1a69498
MD5 fcf321fee0754166395ea70169224c79
BLAKE2b-256 d1d96d6cabf675e3f0f1df93429be713fdb41adcbb73dbf02a42fa48feccef16

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.10-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 cd32a7a3fb6bad23f6786c9c6499f7b5e899bf383287a91f05f1e30ee382599e
MD5 fa181adf9ba19f04755fdc1cc6ff02be
BLAKE2b-256 42e76f81b8d0e6711c4a642d68b60141f92c835e4406561f83a2581f9b01e89c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.10-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 acd0e22768a5ee2ccff4b71dd06c3b2c1f93a42be5d2a11ab1aab3e885500def
MD5 5d5513c95f65b6ca6c7c752273111f99
BLAKE2b-256 7c50aa7cb5c8a28b3c5d8a9afcdb1b98bb18f1d45de47ff9cec8966670802b89

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.10-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8eae163e23416ba05de2d6b48870dbafec13f9a9c817195fe9215e5e8c0e1440
MD5 d6063cc88ab18ae6187d15428fdc2ad8
BLAKE2b-256 5bb7281d9a63ef636e8b7f1355ddfffd7f896113e6f35f2100d68d8f8453d734

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.10-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3aea9123228d018e99f64d36c98097c3f8f6588d80d4de5aaab0bd5804ebe837
MD5 31287f037710a71ce1b92c2204500061
BLAKE2b-256 cd95867a71fbafff5cec92753cd7208f2bfde6d2db5de3bdd19cb302af247e1b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.10-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e3e9850836dee26f1b801cb6bd8919ea1dd1229357d0c06a25e67665d179ef59
MD5 205342a8a9218a16c76afa183b26d2b4
BLAKE2b-256 da8aafee266adc3dc40ee2fa2f266582ed27635fbd6a2251a771d2e7a5859ab3

See more details on using hashes here.

Provenance

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

This release

0.5.10 This release

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