Metadata-Version: 2.4
Name: io7app
Version: 0.1.0
Summary: Python app-server framework for the io7 IoT platform
Project-URL: Homepage, https://github.com/io7lab/io7app
Project-URL: Documentation, https://github.com/io7lab/io7app/blob/main/USER_GUIDE.md
Project-URL: Source, https://github.com/io7lab/io7app
Project-URL: Issues, https://github.com/io7lab/io7app/issues
Author: Yoonseok Hur
License: MIT License
        
        Copyright (c) 2026 Yoonseok Hur
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: automation,io7,iot,mqtt
Classifier: Development Status :: 4 - Beta
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 :: Only
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 :: Communications
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Requires-Dist: paho-mqtt<3.0,>=1.6
Requires-Dist: python-dotenv>=1.0
Provides-Extra: cron
Requires-Dist: croniter>=2.0; extra == 'cron'
Provides-Extra: dev
Requires-Dist: croniter>=2.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# io7app

A small, intuitive Python framework for writing **app servers** on the [io7 IoT platform](https://github.com/io7lab/).

You decorate Python functions with the device events they react to and the schedules they fire on. The framework owns the MQTT connection, topic routing, JSON envelope handling, scheduling, and dynamic register/unregister. Your code stays focused on business logic.

## The io7 platform — where this library fits

```
┌──────────┐                  ┌──────────┐                  ┌─────────────────┐
│  Devices │ ── events ──▶    │  Broker  │ ── events ──▶    │       App       │
│ (sensors,│                  │(Mosquitto)│                  │  (this library, │
│actuators)│ ◀── commands ──  │          │ ◀── commands ──  │   one process)  │
└──────────┘                  └──────────┘                  └─────────────────┘
   (many)                                                        (one)
```

io7 separates the world into two roles. **Devices** publish *events* (sensor readings, status changes) and receive *commands* (actuation requests). **Apps** subscribe to events from any device and publish commands to any device — they are where the IoT business logic lives ("if temperature drops, turn the valve on", "when the switch flips, mirror it on the lamp").

This library implements **only the App side**. Device firmware lives in the io7 [device libraries](https://github.com/io7lab/IO7FuPython) (ESP32, ESP8266, MicroPython).

## Install

```bash
pip install io7app
# Optional, only if you use @inject(cron=...)
pip install croniter
```

Requires Python ≥ 3.10. Talks to any standard MQTT broker (Mosquitto, EMQX, HiveMQ, the io7 platform itself).

## Configure

Drop a `.env` next to your script (copy from `.env.example`):

```
IO7_SERVER=iot201.ddns.net
IO7_APP_ID=app3
IO7_TOKEN=app3
```

That's the minimum. TLS, port overrides, and log levels are documented in the user guide.

## Status

- Version 0.1.0
- ~640 lines of Python across three small modules (router, scheduler, app)
- 71 tests, all green
- One dependency: `paho-mqtt`. Plus `python-dotenv` for config and optionally `croniter` for cron schedules.

## Where to go next

- **[USER_GUIDE.md](USER_GUIDE.md)** — write your first app, decorator reference, scheduling, dynamic register/unregister, debug logging. Every claim in the guide is exercised by a test.
- **[examples/](examples/)** — five runnable apps: switch/lamp, thermostat/valve, lux auto-lamp, scheduled inject, wildcard tracing.
- **[docs/superpowers/specs/](docs/superpowers/specs/)** — design document.
- **[docs/superpowers/plans/](docs/superpowers/plans/)** — implementation plan.

## Develop

```bash
git clone <this-repo>
cd io7app
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## Design principles

- **Small.** Three modules, one class, four decorators.
- **Intuitive.** A working app is 3-5 lines of business logic.
- **Honest.** No magic — handler signatures are inspected, not assumed; dropped messages are silent only when the spec says so; warnings spell out exactly what was deduplicated and why.
- **Optimal where it counts.** Static topics dispatch in O(1); wildcards compile to a regex once; overlapping decorators are consolidated at registration time so handlers never double-fire.

## License

MIT — see [LICENSE](LICENSE). Same as the rest of the io7lab packages.
