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 17, 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 17, 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.3.tar.gz (379.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.3-cp314-abi3-win_amd64.whl (589.7 kB view details)

Uploaded CPython 3.14+Windows x86-64

cosalette-0.5.3-cp314-abi3-musllinux_1_2_x86_64.whl (933.1 kB view details)

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

cosalette-0.5.3-cp314-abi3-musllinux_1_2_aarch64.whl (900.9 kB view details)

Uploaded CPython 3.14+musllinux: musl 1.2+ ARM64

cosalette-0.5.3-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (730.2 kB view details)

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

cosalette-0.5.3-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (733.0 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARMv7l

cosalette-0.5.3-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (725.6 kB view details)

Uploaded CPython 3.14+manylinux: glibc 2.17+ ARM64

cosalette-0.5.3-cp314-abi3-macosx_11_0_arm64.whl (695.3 kB view details)

Uploaded CPython 3.14+macOS 11.0+ ARM64

cosalette-0.5.3-cp314-abi3-macosx_10_12_x86_64.whl (697.8 kB view details)

Uploaded CPython 3.14+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: cosalette-0.5.3.tar.gz
  • Upload date:
  • Size: 379.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.3.tar.gz
Algorithm Hash digest
SHA256 083acf1bcd5bb679a383f89e717224f2522478057319db9db850ff62c52a0ac4
MD5 a772ea379ba8b95b13528d89a4f9d65d
BLAKE2b-256 1553b2e2710457831b9cbef17df4fa3f7dd1d3a433a4b10e1c6ea30eb1eabed5

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cosalette-0.5.3-cp314-abi3-win_amd64.whl
  • Upload date:
  • Size: 589.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.3-cp314-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4266a3f50a14e898b914d535e06e49ce04277c4916ac0a78e5b4dbc395e75af3
MD5 3bce507227416422942a0f5a7623c2f9
BLAKE2b-256 e944b6cf0604f25f4bd35d96a52f719869f69c6f1cc848575192992cfb92d135

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.3-cp314-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 cebd65f0ed48095e116db0bfabeee5f6462a8e4dc2e7c9ee429e664df184469f
MD5 2669bc6157c4f65d7e0e4443dbd0bd55
BLAKE2b-256 4d4a54d1574a404dabbdc27b72ab0b26c1f37709a87773e5bfead9ad643a263d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.3-cp314-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 e44381929c45acac060a2f1a43d979f01e4dd06bd049a58153f4b4959f48bb9d
MD5 d7265cf9bb0a04fcd9c5d5f278a28500
BLAKE2b-256 5e3fe5c34edd60f66044b4c8000f3e851c7c671f3f2ea13e0603ced40d8ac11a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.3-cp314-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 93215c35358785898da022cc85776d0ecc7b92ff87a3ea114dc309bae8f4915e
MD5 88e23ccc701e164ac8fe702fe31224d7
BLAKE2b-256 7ab6d346005b9747ff024d9329869669899aa3c408d34d535c2a7fcd3e8ccdec

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.3-cp314-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl
Algorithm Hash digest
SHA256 7f304ff34a1e639886de133ee7fd7d226f36c93ea376d422b34f1c6dc05b5ff0
MD5 4dec840f35cd5daa4b21de606eddcf0f
BLAKE2b-256 a8f7e0974e495829ca505875c7e35ebf1a673fba2daa514d47145b856798a594

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.3-cp314-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 b8390324d798e55a4d1708ab5c3ee1374db0c89dbdf61984916441151b094ae7
MD5 cdae06facf364caf332799c02dc42fb7
BLAKE2b-256 5cf635efdf7f9daa4177b523c78d498705d2df7ed49b5ba90121a2ae02dd4fcc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.3-cp314-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e3d48a54c3c5101ec295836a77498461defdaa6195df41bfee4e38af26d4ebfb
MD5 eae19b542c9e8282a1941d39f0a2597c
BLAKE2b-256 9c14bca6a98a443239a06e78e3c6c7ae71d230b441fc392f4725f091a4f36755

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for cosalette-0.5.3-cp314-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 81f7ccce943d94392d1c0638cf99e18f8729e8c604de2b412f6fdeab7c06646c
MD5 fb89690bdf0839fc50208d760dde0b42
BLAKE2b-256 116af1295aba34148815f9b7afab20cf075ce16ee6132a06d45a01758b70b286

See more details on using hashes here.

Provenance

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

0.5.5

9 files

0.5.4

9 files

This release

0.5.3 This release

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