invisoutlet 1.0.0__tar.gz

invisoutlet-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tinkerborg
+
+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.

invisoutlet-1.0.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: invisoutlet
+Version: 1.0.0
+Summary: Python client library and CLI for InvisOutlet smart outlets
+Author: tinkerborg
+License-Expression: MIT
+Project-URL: Documentation, https://tinkerborg.github.io/invisoutlet/
+Project-URL: Homepage, https://github.com/tinkerborg/invisoutlet
+Project-URL: Issues, https://github.com/tinkerborg/invisoutlet/issues
+Project-URL: Repository, https://github.com/tinkerborg/invisoutlet
+Keywords: invisoutlet,smart outlet,home automation,iot,websocket
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: zeroconf>=0.131
+Provides-Extra: cli
+Requires-Dist: typer>=0.12; extra == "cli"
+Requires-Dist: rich>=13; extra == "cli"
+Requires-Dist: questionary>=2.0; extra == "cli"
+Provides-Extra: dev
+Requires-Dist: invisoutlet[cli]; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: invisoutlet[cli]; extra == "docs"
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
+Requires-Dist: mkdocs-click>=0.8; extra == "docs"
+Requires-Dist: mkdocs-gen-files>=0.5; extra == "docs"
+Dynamic: license-file
+
+# invisoutlet
+
+[![ci](https://github.com/tinkerborg/invisoutlet/actions/workflows/ci.yaml/badge.svg)](https://github.com/tinkerborg/invisoutlet/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/gh/tinkerborg/invisoutlet/graph/badge.svg)](https://codecov.io/gh/tinkerborg/invisoutlet)
+[![docs](https://github.com/tinkerborg/invisoutlet/actions/workflows/docs.yaml/badge.svg)](https://tinkerborg.github.io/invisoutlet/)
+[![PyPI](https://img.shields.io/pypi/v/invisoutlet)](https://pypi.org/project/invisoutlet/)
+[![Python](https://img.shields.io/pypi/pyversions/invisoutlet)](https://pypi.org/project/invisoutlet/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/tinkerborg/invisoutlet/blob/HEAD/LICENSE)
+
+A Python client library and command-line tool for InvisOutlet smart outlets. It
+talks to the device directly over its local network API, so there's no cloud in
+the loop. This is an independent project, and it isn't affiliated with or
+endorsed by InvisOutlet.
+
+## Features
+
+- **Local-only** — speaks the device's on-device WebSocket API directly; no
+  cloud account, no internet dependency.
+- **Push-driven** — subscribe to live sensor, outlet, and OTA updates as the
+  device emits them; auto-reconnects with backoff.
+- **Full device surface** — outlets, nightlight and Aura color arrays (static
+  color/temperature, per-LED palettes, animated effects), sensor readings,
+  configuration, accessory names, calibration, and OTA firmware updates.
+- **Typed, async API** — `asyncio` throughout, parsed dataclass models, and
+  exceptions on failure (no error codes to check).
+- **`invis` CLI** — discover devices on the network and drive every command
+  from the terminal.
+- **Lightweight core** — the library depends only on `aiohttp` and `zeroconf`;
+  CLI deps are an optional extra.
+
+## Install
+
+```bash
+uv pip install -e ".[dev]"          # library + CLI + tests, into the project venv
+uv tool install --editable ".[cli]" # or just the `invis` command, globally
+```
+
+The library itself only needs `aiohttp` and `zeroconf`; the `invis` CLI's
+extra dependencies (`typer`, `rich`, `questionary`) live under the `cli` extra,
+so embedding the library elsewhere stays lightweight.
+
+## Using the library
+
+```python
+import asyncio
+from invisoutlet import InvisOutletClient
+
+async def main() -> None:
+    async with InvisOutletClient("10.42.44.90") as client:
+        print(await client.get_device_info())
+        await client.set_outlet(1, True)
+
+asyncio.run(main())
+```
+
+## Using the CLI
+
+```bash
+invis default select     # discover, pick, and save a default device
+invis device info
+invis outlet on 1
+invis watch --us
+invis nightlight aura color 200 90
+```
+
+The first time you run a command without a saved device, the CLI scans the
+network and lets you pick one.
+
+## Documentation
+
+The full API and CLI reference lives on the
+[documentation site](https://tinkerborg.github.io/invisoutlet/).
+
+## Development
+
+```bash
+uv pip install -e ".[dev]"
+uv run pytest -q
+```
+
+## License
+
+[MIT](https://github.com/tinkerborg/invisoutlet/blob/HEAD/LICENSE)

invisoutlet-1.0.0/README.md

@@ -0,0 +1,83 @@
+# invisoutlet
+
+[![ci](https://github.com/tinkerborg/invisoutlet/actions/workflows/ci.yaml/badge.svg)](https://github.com/tinkerborg/invisoutlet/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/gh/tinkerborg/invisoutlet/graph/badge.svg)](https://codecov.io/gh/tinkerborg/invisoutlet)
+[![docs](https://github.com/tinkerborg/invisoutlet/actions/workflows/docs.yaml/badge.svg)](https://tinkerborg.github.io/invisoutlet/)
+[![PyPI](https://img.shields.io/pypi/v/invisoutlet)](https://pypi.org/project/invisoutlet/)
+[![Python](https://img.shields.io/pypi/pyversions/invisoutlet)](https://pypi.org/project/invisoutlet/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/tinkerborg/invisoutlet/blob/HEAD/LICENSE)
+
+A Python client library and command-line tool for InvisOutlet smart outlets. It
+talks to the device directly over its local network API, so there's no cloud in
+the loop. This is an independent project, and it isn't affiliated with or
+endorsed by InvisOutlet.
+
+## Features
+
+- **Local-only** — speaks the device's on-device WebSocket API directly; no
+  cloud account, no internet dependency.
+- **Push-driven** — subscribe to live sensor, outlet, and OTA updates as the
+  device emits them; auto-reconnects with backoff.
+- **Full device surface** — outlets, nightlight and Aura color arrays (static
+  color/temperature, per-LED palettes, animated effects), sensor readings,
+  configuration, accessory names, calibration, and OTA firmware updates.
+- **Typed, async API** — `asyncio` throughout, parsed dataclass models, and
+  exceptions on failure (no error codes to check).
+- **`invis` CLI** — discover devices on the network and drive every command
+  from the terminal.
+- **Lightweight core** — the library depends only on `aiohttp` and `zeroconf`;
+  CLI deps are an optional extra.
+
+## Install
+
+```bash
+uv pip install -e ".[dev]"          # library + CLI + tests, into the project venv
+uv tool install --editable ".[cli]" # or just the `invis` command, globally
+```
+
+The library itself only needs `aiohttp` and `zeroconf`; the `invis` CLI's
+extra dependencies (`typer`, `rich`, `questionary`) live under the `cli` extra,
+so embedding the library elsewhere stays lightweight.
+
+## Using the library
+
+```python
+import asyncio
+from invisoutlet import InvisOutletClient
+
+async def main() -> None:
+    async with InvisOutletClient("10.42.44.90") as client:
+        print(await client.get_device_info())
+        await client.set_outlet(1, True)
+
+asyncio.run(main())
+```
+
+## Using the CLI
+
+```bash
+invis default select     # discover, pick, and save a default device
+invis device info
+invis outlet on 1
+invis watch --us
+invis nightlight aura color 200 90
+```
+
+The first time you run a command without a saved device, the CLI scans the
+network and lets you pick one.
+
+## Documentation
+
+The full API and CLI reference lives on the
+[documentation site](https://tinkerborg.github.io/invisoutlet/).
+
+## Development
+
+```bash
+uv pip install -e ".[dev]"
+uv run pytest -q
+```
+
+## License
+
+[MIT](https://github.com/tinkerborg/invisoutlet/blob/HEAD/LICENSE)

invisoutlet-1.0.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools>=68.0", "wheel"]
+
+[project]
+authors = [{name = "tinkerborg"}]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Home Automation",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+dependencies = [
+  "aiohttp>=3.9",
+  "zeroconf>=0.131",
+]
+description = "Python client library and CLI for InvisOutlet smart outlets"
+keywords = ["invisoutlet", "smart outlet", "home automation", "iot", "websocket"]
+license = "MIT"
+name = "invisoutlet"
+readme = "README.md"
+requires-python = ">=3.13"
+version = "1.0.0"
+
+[project.urls]
+Documentation = "https://tinkerborg.github.io/invisoutlet/"
+Homepage = "https://github.com/tinkerborg/invisoutlet"
+Issues = "https://github.com/tinkerborg/invisoutlet/issues"
+Repository = "https://github.com/tinkerborg/invisoutlet"
+
+[project.scripts]
+invis = "invisoutlet.cli.app:app"
+
+[project.optional-dependencies]
+# The CLI (`invis`) needs these; the library itself does not. Installed via
+# `invisoutlet[cli]`. Kept out of the base deps so embedding the library
+# (e.g. in a Home Assistant integration) doesn't pull in typer/rich/questionary.
+cli = [
+  "typer>=0.12",
+  "rich>=13",
+  "questionary>=2.0",
+]
+dev = [
+  "invisoutlet[cli]",
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=5.0",
+]
+docs = [
+  "invisoutlet[cli]",
+  "mkdocs>=1.6",
+  "mkdocs-material>=9.5",
+  "mkdocstrings[python]>=0.26",
+  "mkdocs-click>=0.8",
+  "mkdocs-gen-files>=0.5",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

invisoutlet-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

invisoutlet-1.0.0/src/invisoutlet/__init__.py

@@ -0,0 +1,58 @@
+"""Python client library for InvisOutlet smart outlets."""
+
+from .client import (
+    ColorEffect,
+    InvisOutletClient,
+    OtaTarget,
+    target_for_device_type,
+)
+from .discovery import DiscoveredDevice, discover
+from .exceptions import (
+    InvisOutletCommandError,
+    InvisOutletConnectionError,
+    InvisOutletError,
+    InvisOutletTimeoutError,
+)
+from .models import (
+    AccessoryName,
+    AvailableUpdates,
+    ColorLedEntry,
+    ColorLightState,
+    DeviceConfig,
+    DeviceInfo,
+    FirmwareRelease,
+    FirmwareUpdate,
+    NightlightState,
+    OtaProgress,
+    OtaResult,
+    OutletStatus,
+    SensorData,
+    SubDeviceInfo,
+)
+
+__all__ = [
+    "AccessoryName",
+    "AvailableUpdates",
+    "ColorEffect",
+    "ColorLedEntry",
+    "ColorLightState",
+    "DeviceConfig",
+    "DeviceInfo",
+    "DiscoveredDevice",
+    "FirmwareRelease",
+    "FirmwareUpdate",
+    "InvisOutletClient",
+    "InvisOutletCommandError",
+    "InvisOutletConnectionError",
+    "InvisOutletError",
+    "InvisOutletTimeoutError",
+    "NightlightState",
+    "OtaProgress",
+    "OtaResult",
+    "OtaTarget",
+    "OutletStatus",
+    "SensorData",
+    "SubDeviceInfo",
+    "discover",
+    "target_for_device_type",
+]

invisoutlet-1.0.0/src/invisoutlet/cli/__init__.py

@@ -0,0 +1,8 @@
+"""Command-line interface for the InvisOutlet client.
+
+The console entry point ``invis`` resolves to :data:`app`.
+"""
+
+from .app import app
+
+__all__ = ["app"]

invisoutlet-1.0.0/src/invisoutlet/cli/app.py

@@ -0,0 +1,61 @@
+"""The Typer application and global options.
+
+This module defines the ``app`` referenced by the ``invis`` console entry
+point. Commands live in :mod:`invisoutlet.cli.commands` and are attached
+here via each module's ``register`` function.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+import typer
+
+from .commands import register_all
+from .state import CLIState
+
+app = typer.Typer(
+    name="invis",
+    help="Command-line tool for InvisOutlet smart outlets.",
+    rich_markup_mode="rich",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    """Print the package version and exit when ``--version`` is passed."""
+    if not value:
+        return
+    try:
+        typer.echo(version("invisoutlet"))
+    except PackageNotFoundError:
+        typer.echo("unknown")
+    raise typer.Exit
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    host: str | None = typer.Option(
+        None, "--host", help="Device IP address (overrides the saved default)."
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Skip confirmation for destructive commands."
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """Store global options for the invoked command."""
+    ctx.obj = CLIState(host=host, yes=yes)
+
+
+register_all(app)
+
+# Click command object, exposed for docs generation (mkdocs-click).
+cli = typer.main.get_command(app)

invisoutlet-1.0.0/src/invisoutlet/cli/commands/__init__.py

@@ -0,0 +1,34 @@
+"""Command groups for the InvisOutlet CLI.
+
+Each module exposes a ``register(app)`` function that attaches its commands to
+the shared Typer app — most as noun subgroups (`device`, `nightlight`, …), a few
+as flat top-level commands (`watch`, `discover`).
+"""
+
+from . import (
+    deco,
+    default,
+    device,
+    discover,
+    name,
+    nightlight,
+    ota,
+    outlet,
+    watch,
+)
+
+
+def register_all(app: object) -> None:
+    """Register every command module against the Typer ``app``."""
+    default.register(app)
+    device.register(app)
+    nightlight.register(app)
+    outlet.register(app)
+    deco.register(app)
+    name.register(app)
+    discover.register(app)
+    ota.register(app)
+    watch.register(app)
+
+
+__all__ = ["register_all"]

invisoutlet-1.0.0/src/invisoutlet/cli/commands/deco.py

@@ -0,0 +1,77 @@
+"""The ``deco`` group: control the attached InvisDeco faceplate."""
+
+from __future__ import annotations
+
+import typer
+
+from invisoutlet import InvisOutletClient
+
+from .. import render
+from ..state import confirm_destructive, run_with_client
+
+deco_app = typer.Typer(
+    name="deco", help="Control the attached InvisDeco faceplate.", no_args_is_help=True
+)
+calibrate_app = typer.Typer(
+    name="calibrate", help="Calibrate the faceplate's sensors.", no_args_is_help=True
+)
+deco_app.add_typer(calibrate_app)
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the ``deco`` group to ``app``."""
+    app.add_typer(deco_app)
+
+
+@deco_app.command()
+def restart(ctx: typer.Context) -> None:
+    """Restart the InvisDeco."""
+    run_with_client(ctx.obj, _restart)
+
+
+@deco_app.command()
+def reset(ctx: typer.Context) -> None:
+    """Reset the InvisDeco (clears air-quality calibration)."""
+    confirm_destructive(ctx.obj, "deco-reset")
+    run_with_client(ctx.obj, _reset)
+
+
+@calibrate_app.command()
+def occupancy(
+    ctx: typer.Context,
+    seconds: int = typer.Argument(..., help="Calibration duration in seconds."),
+) -> None:
+    """Run occupancy-sensor calibration."""
+    run_with_client(ctx.obj, lambda c: _calibrate_occupancy(c, seconds))
+
+
+@calibrate_app.command()
+def climate(
+    ctx: typer.Context,
+    temperature: float = typer.Argument(..., help="Reference temperature in °C."),
+    humidity: float = typer.Argument(..., help="Reference relative humidity in %."),
+) -> None:
+    """Calibrate temperature and humidity to reference values."""
+    run_with_client(ctx.obj, lambda c: _calibrate_climate(c, temperature, humidity))
+
+
+async def _restart(client: InvisOutletClient) -> None:
+    await client.restart_invisdeco()
+    render.console.print("[green]✓[/green] InvisDeco restart command sent.")
+
+
+async def _reset(client: InvisOutletClient) -> None:
+    await client.reset_invisdeco()
+    render.console.print("[green]✓[/green] InvisDeco reset command sent.")
+
+
+async def _calibrate_occupancy(client: InvisOutletClient, seconds: int) -> None:
+    await client.calibrate_occupancy(seconds)
+    render.console.print(f"[green]✓[/green] Occupancy calibration started for {seconds}s.")
+
+
+async def _calibrate_climate(
+    client: InvisOutletClient, temperature: float, humidity: float
+) -> None:
+    await client.calibrate_temp_humidity(temperature, humidity)
+    render.console.print(f"[green]✓[/green] Calibrated to {temperature} °C / {humidity}% RH.")

invisoutlet-1.0.0/src/invisoutlet/cli/commands/default.py

@@ -0,0 +1,89 @@
+"""The ``default`` group: manage the persisted default device."""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+
+from invisoutlet import InvisOutletClient, InvisOutletError
+
+from ..config import (
+    DefaultDevice,
+    clear_default_device,
+    get_default_device,
+    set_default_device,
+)
+from ..picker import pick_device
+from ..render import console
+
+default_app = typer.Typer(
+    name="default",
+    help="Manage the default device.",
+    no_args_is_help=True,
+)
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the ``default`` group to ``app``."""
+    app.add_typer(default_app)
+
+
+@default_app.command()
+def select(
+    host: str | None = typer.Option(
+        None, "--host", help="Set this IP directly instead of running the picker."
+    ),
+) -> None:
+    """Choose a device (via picker, or --host) and save it as the default."""
+    if host is not None:
+        device = asyncio.run(_probe(host))
+    else:
+        chosen = asyncio.run(pick_device())
+        if chosen is None:
+            raise typer.Exit(code=1)
+        device = DefaultDevice(
+            host=chosen.host,
+            name=chosen.name,
+            serial_number=chosen.serial_number,
+        )
+
+    set_default_device(device)
+    console.print(
+        f"[green]✓[/green] Default device set: {device.name or device.host} "
+        f"([cyan]{device.host}[/cyan])."
+    )
+
+
+@default_app.command()
+def show() -> None:
+    """Show the saved default device."""
+    default = get_default_device()
+    if default is None:
+        console.print("No default device set.")
+        return
+    console.print(f"Host:   [cyan]{default.host}[/cyan]")
+    console.print(f"Name:   {default.name or '—'}")
+    console.print(f"Serial: {default.serial_number or '—'}")
+
+
+@default_app.command()
+def forget() -> None:
+    """Forget the saved default device."""
+    clear_default_device()
+    console.print("[green]✓[/green] Default device cleared.")
+
+
+async def _probe(host: str) -> DefaultDevice:
+    """Best-effort fetch of a device's name/serial for the saved entry.
+
+    Falls back to just the host if the device cannot be reached.
+    """
+    try:
+        async with InvisOutletClient(host) as client:
+            info = await client.get_device_info()
+    except InvisOutletError:
+        return DefaultDevice(host=host)
+    return DefaultDevice(
+        host=host, name=info.device or None, serial_number=info.serial_number or None
+    )