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 Sep 2, 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 Sep 2, 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.8.0.tar.gz (575.8 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.8.0-cp314-abi3-win_amd64.whl (795.3 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.8.0-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.8.0-cp314-abi3-musllinux_1_2_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.8.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (937.7 kB view details)

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

cosalette-0.8.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (938.8 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.8.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (931.4 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.8.0-cp314-abi3-macosx_11_0_arm64.whl (899.7 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.8.0-cp314-abi3-macosx_10_12_x86_64.whl (902.0 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for cosalette-0.8.0.tar.gz
Algorithm Hash digest
SHA256 d4889b7623887e1b009eef16b1bcb45b25528e0c369f5acf6d13d0806a732d1a
MD5 a2e47b9c809d2c981a361f5d1dbb0e46
BLAKE2b-256 e4fc32866ea20dbc14d99248fe119eff1184d84d5bf52be6b338ca57d9700b65

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.8.0-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 795.3 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.8.0-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 557db9d6f8e1dfe6b220dc48ed9d074af694fd734c30803ea3bdcc3b0736615d
MD5 e2a5690258f99e9f643a3db80a867dc4
BLAKE2b-256 617b9d450eab20197ef19b232fd310d25ac743f14d5590488250d95a5a37965c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.8.0-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 cb59353c32f81144fca818e51bea3938e6800157834ba84a5ed40848d33febc6
MD5 6f905969c33dee2983173b3a328c4990
BLAKE2b-256 dc5b6ea31eb86e16f6ddcec4a7b1932255ae74b9376a20db6661239cb04cda18

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.8.0-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 d2f417b433267a1dac475a4a8b6de8ead65e1af21853566672deb339a1d07e6b
MD5 9ba10146c36235da2f3b3d714b54b55d
BLAKE2b-256 46191d91171ef9b702b13f2d0adde578f172188f7fdb5c771598dfbe52973855

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.8.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e1a04950525b07a19550916535325c93c33c362b2b55a496c7504d30e6198022
MD5 4a513519d1c605584253bd1d0f47a343
BLAKE2b-256 8c33e467b53c04536085e190f14399a018c1d6ddd1c3e058fdcdcf61ab898343

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.8.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 60ea4ddeceba02ce326bf0eafef11657ffc68c7d499d9943fbbf9d4038dde757
MD5 ff8c3cc7ece9d402166b2b9ed22aca1b
BLAKE2b-256 7d1b182d37b1166764eba5388835c7073578658cb9bf7d08d9ee8d12fa11b893

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.8.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 b59b933bf3a5e4cefa29a3be51f2cc48f584e8119745aa6b1d068875f75ee402
MD5 295f14b26518b224fb22e2dd5bba1e88
BLAKE2b-256 6e83f0fa577d72573be42edb9e3f54a5a45f8e39eacd829e7368c3ff91c069f9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.8.0-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 57e5154626a6ff0f3a78f8ff8dd0a59a9c8652eedff1066a2b31c7a2d7bfb326
MD5 381d9540025dff57c56d049f834eb46d
BLAKE2b-256 13b10b1823d7028c6d7377ae1dc88c9104f2e9427e93eaf67b49bd16b2698769

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.8.0-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6138ebe575e39683662cc68827ca714d3515adb3244c620d5735cb50b289897a
MD5 5d40bc4db7cfd1bd87a8df63d37ef261
BLAKE2b-256 9f4b0fefbf8f585369c2322a8a47a6081aee78e033bf3b5c4f6bc61d2b0e5301

See more details on using hashes here.

Provenance

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

This release

0.8.0 This release

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

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