Metadata-Version: 2.4
Name: cosalette
Version: 0.2.1
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Dist: aiomqtt>=2.5.0
Requires-Dist: orjson>=3.10
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: typer>=0.12
License-File: LICENSE
Summary: an opinionated Python framework for building IoT-to-MQTT bridge applications
Keywords: iot,mqtt,home-automation,asyncio,framework
Author-email: Fabian Koerner <mail@fabiankoerner.com>
License-Expression: MIT
Requires-Python: >=3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/ff-fab/cosalette/blob/main/CHANGELOG.md
Project-URL: Documentation, https://ff-fab.github.io/cosalette/
Project-URL: Homepage, https://github.com/ff-fab/cosalette
Project-URL: Issues, https://github.com/ff-fab/cosalette/issues
Project-URL: Repository, https://github.com/ff-fab/cosalette

# cosalette

An opinionated Python framework for building IoT-to-MQTT bridge applications.

[![CI](https://github.com/ff-fab/cosalette/actions/workflows/ci.yml/badge.svg)](https://github.com/ff-fab/cosalette/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/ff-fab/cosalette/graph/badge.svg)](https://codecov.io/gh/ff-fab/cosalette)
[![Tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/ff-fab/18bf35c516091db0ca767ebf497f2b8f/raw/test-badge.json)](https://gistpreview.github.io/?18bf35c516091db0ca767ebf497f2b8f/test-report.html)
[![Docs](https://github.com/ff-fab/cosalette/actions/workflows/docs.yml/badge.svg)](https://ff-fab.github.io/cosalette/)
[![PyPI](https://img.shields.io/pypi/v/cosalette)](https://pypi.org/project/cosalette/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-%E2%89%A53.14-blue)](https://www.python.org/)

**[Documentation](https://ff-fab.github.io/cosalette/)** ·
**[Quickstart](https://ff-fab.github.io/cosalette/getting-started/quickstart/)** ·
**[API Reference](https://ff-fab.github.io/cosalette/reference/api/)**

---

## 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.

### Key Features

- **Declarative device registration** — `@app.command()`, `@app.device()`, and
  `@app.telemetry()` decorators
  ([guide](https://ff-fab.github.io/cosalette/guides/command-device/))
- **Hexagonal architecture** — protocol-based ports with swappable adapters
  ([concept](https://ff-fab.github.io/cosalette/concepts/hexagonal/))
- **Structured JSON logging** — per-device context, configurable levels
  ([concept](https://ff-fab.github.io/cosalette/concepts/logging/))
- **Health & heartbeats** — LWT crash detection, periodic JSON heartbeats, per-device
  availability
  ([concept](https://ff-fab.github.io/cosalette/concepts/health-reporting/))
- **Structured error publishing** — domain errors published to MQTT with type mapping
  ([concept](https://ff-fab.github.io/cosalette/concepts/error-handling/))
- **Pydantic settings** — type-safe configuration from env vars and `.env` files
  ([guide](https://ff-fab.github.io/cosalette/guides/configuration/))
- **CLI for free** — `--dry-run`, `--version`, `--log-level`, `--env-file` via Typer
  ([reference](https://ff-fab.github.io/cosalette/reference/cli/))
- **Test-friendly** — `MockMqttClient`, `FakeClock`, pytest fixtures included
  ([guide](https://ff-fab.github.io/cosalette/guides/testing/))

## Quick Example

```python
import cosalette

app = cosalette.App(name="weather2mqtt", 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](https://ff-fab.github.io/cosalette/getting-started/quickstart/) for a
complete walkthrough.

## Installation

```bash
pip install cosalette
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add cosalette
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commands, project
structure, and code quality standards.

## Documentation

Full documentation is published at
**[ff-fab.github.io/cosalette](https://ff-fab.github.io/cosalette/)**.

| Section                                                                | What you'll find                                       |
| ---------------------------------------------------------------------- | ------------------------------------------------------ |
| [Getting Started](https://ff-fab.github.io/cosalette/getting-started/) | Installation, quickstart tutorial                      |
| [Concepts](https://ff-fab.github.io/cosalette/concepts/)               | Architecture, MQTT topics, lifecycle, hexagonal design |
| [How-To Guides](https://ff-fab.github.io/cosalette/guides/)            | Step-by-step guides for each feature                   |
| [Reference](https://ff-fab.github.io/cosalette/reference/)             | API docs, CLI options, payload schemas                 |
| [ADRs](https://ff-fab.github.io/cosalette/adr/)                        | Architecture Decision Records                          |

## License

MIT License. See [LICENSE](LICENSE) for details.

