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 28, 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 28, 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.0.tar.gz (524.1 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.0-cp314-abi3-win_amd64.whl (740.4 kB view details)

Uploaded CPython 3.14+Windows x86-64

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

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.7.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (882.7 kB view details)

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

cosalette-0.7.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (883.8 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.7.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (876.4 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.7.0-cp314-abi3-macosx_11_0_arm64.whl (844.7 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.7.0-cp314-abi3-macosx_10_12_x86_64.whl (847.0 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.7.0.tar.gz
  • Upload date:
  • Size: 524.1 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.0.tar.gz
Algorithm Hash digest
SHA256 aa128a34384f90a595d745a85774ae13467f8d41a48190a71701dd16f75725ef
MD5 c2ea4909e311e4097381d9e0f21e8a49
BLAKE2b-256 33ebc496f1b630231876359a585e2bbdc70ff10ded5a05d6e580a5210c0eecff

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.7.0-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 740.4 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.0-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 afa243acd517756fcc486880e662a1e2370e3b1b8190c00ba2bd20e1752a60b1
MD5 af351dd312a37dd8863669d8b9beb67a
BLAKE2b-256 b757e60cd71155805ba9fd98f386279b23df2e803c94e35c59c8b7f7ef234d39

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.0-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 28b2063cf8c54375a96aa9a7cd12eed0c251a390efc0a2e2d8dab9fdc53c4ef6
MD5 29ce0a89c0752fd0111ac54baed7c2e2
BLAKE2b-256 d06aa294aa0e6bd6bdeb987136ba6b29d1c0e32e4bc26ff38cf89f7c6b71a1b7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.0-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 b49c214fbc99ea222b30599a8729f7abd97a858e27d918ad0cbf802c5e307f59
MD5 16c6a21f3add0c5770dae218d654905a
BLAKE2b-256 c4b64db94b0f24869b79284ce9aa46c6580d4a0b62e08dcde764525e590be921

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.0-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 91277a07b9c2ab72e8e70b4594848fa09085ce17bfd12a8ea87f89004b6e44c2
MD5 e32153311ba3f515b7a0061aa782c09d
BLAKE2b-256 4c1a7a23f2696f7edbf65b74b69b5c0ab54126414fae3708c9bcbd71e5e4991c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.0-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 fbaf01dc90919788830a1ee4a729a23c004ecfa2b4ba51e888a6844c3a88e321
MD5 6b4982aeafb66cef0a3092e673035e19
BLAKE2b-256 c028259bd2800884a8d448526648b7cb9d61ecbf48b78d56023ac01fb14159db

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.0-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 d698fe20cd8dddffaeefef9afbbc06b8acf4ca75fc5f7eee55f8bd9e9955d9f8
MD5 679fe6bb771ae2cac8a31ae3b17f3a8d
BLAKE2b-256 f1b93b28eacd40a36f331443b0b859d82d9692e58f92606a492802657cb9b561

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.0-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 704dae659864251803113771c65bfdc2526313a43b5be963d9bb999965b810a9
MD5 8a74703f0262ba0965b3f986e55646b6
BLAKE2b-256 fd14b8428ab3c46cb7c6cea2c30f0afbfa65074f983130f1322cd04cc9841fa7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.7.0-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e31a19f17b3dc4c7dc153c4ee569640ef7ea9bdd0eb74362873ab8ee024b44ff
MD5 feb41b0a61d086134ef6c113665e693c
BLAKE2b-256 68798a5496b4ee108c4e89ef6cd94da1ec07e7f39f8a59f069e9ad882b8e39a7

See more details on using hashes here.

Provenance

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

0.8.0

9 files

0.7.1

9 files

This release

0.7.0 This release

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