Metadata-Version: 2.4
Name: kamio
Version: 1.0.0b1
Summary: Декларативный асинхронный IoT-фреймворк для Python с поддержкой MQTT
Author-email: Данил Сытников <d.sytnikov@int-sys.ru>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Peim0n/kamio
Project-URL: Repository, https://github.com/Peim0n/kamio.git
Project-URL: Documentation, https://github.com/Peim0n/kamio#readme
Project-URL: Bug Tracker, https://github.com/Peim0n/kamio/issues
Keywords: iot,mqtt,home-automation,asyncio,framework,smart-home
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Hardware
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gmqtt==0.7.0
Provides-Extra: gpio
Requires-Dist: gpiod>=1.6.0; extra == "gpio"
Provides-Extra: serial
Requires-Dist: pyserial>=3.5; extra == "serial"
Provides-Extra: http
Requires-Dist: aiohttp>=3.8.0; extra == "http"
Provides-Extra: all-drivers
Requires-Dist: gpiod>=1.6.0; extra == "all-drivers"
Requires-Dist: pyserial>=3.5; extra == "all-drivers"
Requires-Dist: aiohttp>=3.8.0; extra == "all-drivers"
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pylint>=2.17; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Requires-Dist: pytest-cov>=4.1; extra == "test"
Requires-Dist: pytest-mock>=3.11; extra == "test"
Provides-Extra: full
Requires-Dist: gpiod>=1.6.0; extra == "full"
Requires-Dist: pyserial>=3.5; extra == "full"
Requires-Dist: aiohttp>=3.8.0; extra == "full"
Requires-Dist: black>=23.0; extra == "full"
Requires-Dist: isort>=5.12; extra == "full"
Requires-Dist: mypy>=1.0; extra == "full"
Requires-Dist: pylint>=2.17; extra == "full"
Requires-Dist: pytest>=7.4; extra == "full"
Requires-Dist: pytest-asyncio>=0.21; extra == "full"
Requires-Dist: pytest-cov>=4.1; extra == "full"
Requires-Dist: pytest-mock>=3.11; extra == "full"
Dynamic: license-file

# Kamio v1.0.0b1

![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)
![Version](https://img.shields.io/badge/version-1.0.0b1--beta-blue.svg)
![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)
![MQTT](https://img.shields.io/badge/MQTT-v5-orange.svg)
![Tests](https://github.com/Peim0n/kamio/actions/workflows/ci.yml/badge.svg)

**Kamio** — декларативный асинхронный IoT-фреймворк для Python на базе MQTT. Описывайте устройства классами, подключайте оборудование драйверами, автоматизируйте правилами.

## Возможности

- **Декларативные устройства** — поля `state`, `telemetry`, `event`, `config` через аннотации Python
- **Драйверы** — GPIO, Serial, Telnet, HTTP, UDP, Modbus TCP, Mock (latency/failure simulation)
- **MQTT v5** — надёжная коммуникация, авто-реконнект, обратная совместимость с legacy-топиками
- **Асинхронность** — полностью `asyncio`, никаких блокирующих вызовов в event loop
- **Правила автоматизации** — реакция на изменения полей и периодические интервалы
- **Plugin System** — изолированные плагины с автоматическим cleanup через `PluginContext`
- **Hot-Reload** — перезагрузка правил и устройств без остановки приложения
- **Custom MQTT Nodes** — произвольные MQTT-узлы с маршрутизацией сообщений
- **Home Assistant Discovery** — lazy-init, активируется только при вызове `enable_ha_discovery()`
- **Конфигурация** — JSON-файлы + переменные окружения `Kamio_*`

## Установка

```bash
pip install kamio
```

### Требования

- Python 3.9+
- MQTT брокер (рекомендуется Mosquitto)

```bash
# Ubuntu/Debian
sudo apt-get install mosquitto mosquitto-clients
# macOS
brew install mosquitto
# Windows: https://mosquitto.org/download/
```

### Дополнительные зависимости

```bash
pip install kamio[gpio]           # GPIO (gpiod)
pip install kamio[serial]          # Serial (pyserial)
pip install kamio[http]            # HTTP (aiohttp)
pip install kamio[all-drivers]   # все внешние зависимости драйверов (gpiod, pyserial, aiohttp)
pip install kamio[dev]            # форматирование, типизация
pip install kamio[test]           # pytest, pytest-asyncio
```

> `UDPDriver`, `TelnetDriver` и `ModbusTCPDriver` используют только стандартную библиотеку Python и доступны без extras.

## Быстрый старт

```python
import asyncio
from kamio import KamioApp, Device, command, state, telemetry

app = KamioApp(mqtt_broker="mqtt://localhost:1883")


class SmartLight(Device):
    power:      bool  = state(default=False, writable=True)
    brightness: int   = state(default=100, min=0, max=255, writable=True)
    energy_wh:  float = telemetry(default=0.0, unit="Wh")

    @command
    async def toggle(self):
        self.power = not self.power
        return {"power": self.power}


class MotionSensor(Device):
    motion_detected: bool = state(default=False, writable=True)


@app.rule(device=MotionSensor, fields=["motion_detected"])
async def on_motion(event, app):
    if event.data["motion_detected"]:
        light = app.devices.get("living_room")
        if light:
            await light.handle_state({"power": True, "brightness": 200})


async def main():
    # Можно передать драйвер: Serial/Telnet/HTTP/UDP/Modbus TCP
    # await app.add_device("living_room", SmartLight, driver=TelnetDriver("10.0.0.10"))
    await app.add_device("living_room", SmartLight)
    await app.add_device("hall_sensor", MotionSensor)
    await app.start()


if __name__ == "__main__":
    asyncio.run(main())
    # ИЛИ блокирующий запуск с обработкой SIGINT/SIGTERM:
    # app.run()
```

## Примеры использования

### Плагины

```python
from kamio.plugins.builtin.metrics_plugin import MetricsPlugin

metrics = await app.load_plugin(MetricsPlugin)
print(metrics.get_counter("device_state_changed"))
```

### Hot-reload правил

```python
app.watch_directory("rules/", "*.py", app.hot_reload.make_rules_handler())
app.enable_hot_reload()
```

### Home Assistant Discovery

```python
app.enable_ha_discovery(prefix="homeassistant")
# HADiscovery создаётся только здесь, не при инициализации KamioApp
```

### Кастомный MQTT-узел

```python
from kamio.core.custom_nodes import CustomNode

class BridgeNode(CustomNode):
    async def handle_message(self, topic: str, payload: bytes):
        print(f"Bridge received: {topic}")

app.register_custom_node("bridge", BridgeNode(app.mqtt_client, "bridge"))
```

### Конфигурация через файл

```python
app = KamioApp(config_path="config.json")
```

```json
{
  "mqtt_broker": "mqtt://broker.local:1883",
  "log_level": "INFO"
}
```

Или через переменные окружения:
```bash
Kamio_MQTT_BROKER=mqtt://broker.local:1883
Kamio_LOG_LEVEL=DEBUG
```

## Структура тестов

```
tests/
  unit/         # изолированные тесты компонентов
  stress/       # тесты под нагрузкой
```

```bash
pytest                          # все тесты
pytest tests/unit/              # только unit
pytest tests/stress/            # только stress
```

## Документация

- [API](docs/api.md) — справочник по всем классам и методам
- [Архитектура](docs/architecture.md) — детальный обзор архитектуры v1.0.0b1

## Лицензия

Apache-2.0 — см. файл [LICENSE](LICENSE)

