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 29, 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 29, 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.7.1.tar.gz (524.2 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.7.1-cp314-abi3-win_amd64.whl (740.5 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.7.1-cp314-abi3-musllinux_1_2_x86_64.whl (1.1 MB view details)

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

cosalette-0.7.1-cp314-abi3-musllinux_1_2_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.7.1-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (882.9 kB view details)

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

cosalette-0.7.1-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (884.0 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.7.1-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (876.5 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.7.1-cp314-abi3-macosx_11_0_arm64.whl (844.9 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.7.1-cp314-abi3-macosx_10_12_x86_64.whl (847.2 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.7.1.tar.gz
  • Upload date:
  • Size: 524.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for cosalette-0.7.1.tar.gz
Algorithm Hash digest
SHA256 214bcece872b59769edc535f3954904113745161baa3f002acf74b623642d872
MD5 8d4a5e92c0ccc747be542d6ea7554038
BLAKE2b-256 106838f009a5d949ef0b9cc6be82fa1526d0bcfca9a989e572d7a4a69bb155b0

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.7.1-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 740.5 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.7.1-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 581f54ffa0884c3dd6492cd1208c322f39a71654506437363416562f1064c733
MD5 8dd3c919fe01458dcf84aa4fe697726e
BLAKE2b-256 6dd022a14445c79f105f0f5356dd8f7968cc77e61362ab5f4a80da9dac250c22

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.1-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 4b3dbbafe9a3d0216a2812f0b4fe5b15e0aac16480ea0ede2e1e4d54f110ba82
MD5 4a8640d5c402a8daf879af03ddefdce3
BLAKE2b-256 d8862a5c745979edec342d543533fdd1e9b2512030d4f1b8cebbd2a815a05c7b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.1-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 33cdc3a39310f8c5c25557547005352b9c9d09542cf23e064e73ba96752fb5c7
MD5 5e797ae8fd49ea36fcce850354f3244d
BLAKE2b-256 5c07ab1bcf9d29e9d0497e84312e2f093556a8a0d69c15a5fcb61b4b52582841

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.1-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ab44f44f4918f814d50322c26aee7d7e1b8585317073e571f6f7c643c3cb272e
MD5 e446aac6d2ddb6c75bab2be040b767d9
BLAKE2b-256 f7e8780aad539edc5452180785b3e6f6de31d0dbd6faaddbca36047fe6520bb5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.1-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 3ab60670fa679c37ffdc0e8f8aaf38617ba737f0d53e0a626c7c14febe38b51b
MD5 aa1dbc648b7cae85d5f811344f39d3de
BLAKE2b-256 e2fda6749f1d965cc15f964d13922f69e48392a56d00487ffe811c20cac4de41

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.1-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 fb6a90f1a8f69b2e426f23125d6abb9368c6e0b1ac5f85388ccd632b0b5e6ec1
MD5 906ed02887d232dc01deed0b9a3fd003
BLAKE2b-256 023a8f3b17ef0ce171d8774fe64560ae6d41ac20a5fbbfd576051da638519280

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.1-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a3531137787b7a55b46adb1708b4ebd356000ecea1676ba4388b4ec509bb5167
MD5 e7f2b0f3d30f5ebf474cf7e07cefa829
BLAKE2b-256 412f1331217a28d35fabff6f1fb0cbf940199671e6601d6e861ccb9ccdee270d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.1-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 51e46cfe79aa5f7c95c7377a6ac8595304a109fac2142b687e9718fcb16e7869
MD5 33057c395b0a613b6dc98ec35e5fa6d0
BLAKE2b-256 62184a3b8f9b8d590c51d54d00f6cd5af7e144c592ce57555a7152061d6f77a8

See more details on using hashes here.

Provenance

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

This release

0.7.1 This release

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