aioleviton 0.1.0__tar.gz

aioleviton-0.1.0/LICENSE

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

aioleviton-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: aioleviton
+Version: 0.1.0
+Summary: Async Python client for the Leviton My Leviton cloud API
+Author: gtxaspec
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gtxaspec/aioleviton
+Project-URL: Repository, https://github.com/gtxaspec/aioleviton
+Project-URL: Issues, https://github.com/gtxaspec/aioleviton/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Dynamic: license-file
+
+# aioleviton
+
+Async Python client for the Leviton My Leviton cloud API.
+
+Supports LWHEM and DAU/LDATA Smart Load Centers with WebSocket real-time push and REST API fallback.
+
+## Features
+
+- Pure `asyncio` with `aiohttp` -- no blocking calls
+- Accepts an injected `aiohttp.ClientSession` for connection pooling
+- WebSocket real-time push notifications with automatic subscription management
+- Full REST API coverage: authentication, device discovery, breaker control, energy history
+- Typed data models with PEP 561 `py.typed` marker
+- Support for both hub types: LWHEM (`IotWhem`) and DAU/LDATA (`ResidentialBreakerPanel`)
+- Two-factor authentication (2FA) support
+
+## Installation
+
+```bash
+pip install aioleviton
+```
+
+## Quick Start
+
+```python
+import aiohttp
+from aioleviton import LevitonClient, LevitonWebSocket
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        # Authenticate
+        client = LevitonClient(session)
+        auth = await client.login("user@example.com", "password")
+
+        # Discover devices
+        permissions = await client.get_permissions()
+        for perm in permissions:
+            if perm.residential_account_id:
+                residences = await client.get_residences(perm.residential_account_id)
+                for residence in residences:
+                    whems = await client.get_whems(residence.id)
+                    panels = await client.get_panels(residence.id)
+
+        # Get breakers for a LWHEM hub
+        for whem in whems:
+            breakers = await client.get_whem_breakers(whem.id)
+            cts = await client.get_cts(whem.id)
+
+        # Connect WebSocket for real-time updates
+        ws = LevitonWebSocket(
+            session=session,
+            token=auth.token,
+            user_id=auth.user_id,
+            user=auth.user,
+            token_created=auth.created,
+            token_ttl=auth.ttl,
+        )
+        await ws.connect()
+
+        # Subscribe to a hub (delivers all child breaker/CT updates)
+        await ws.subscribe("IotWhem", whem.id)
+
+        # Handle notifications
+        ws.on_notification(lambda data: print("Update:", data))
+```
+
+## Supported Devices
+
+| Device | API Model | Hub Type |
+|--------|-----------|----------|
+| LWHEM (Whole Home Energy Module) | `IotWhem` | Wi-Fi hub |
+| DAU / LDATA (Data Acquisition Unit) | `ResidentialBreakerPanel` | Wi-Fi hub |
+| Smart Breaker Gen 1 (trip only) | `ResidentialBreaker` | Child of LWHEM or DAU |
+| Smart Breaker Gen 2 (on/off) | `ResidentialBreaker` | Child of LWHEM or DAU |
+| Current Transformer (CT) | `IotCt` | Child of LWHEM only |
+| LSBMA Add-on CT | `ResidentialBreaker` | Virtual composite |
+
+## Breaker Control
+
+```python
+# Trip a Gen 1 breaker (cannot turn back on remotely)
+await client.trip_breaker(breaker_id)
+
+# Turn on/off a Gen 2 breaker
+await client.turn_on_breaker(breaker_id)
+await client.turn_off_breaker(breaker_id)
+
+# Blink LED on a breaker
+await client.blink_led(breaker_id)
+
+# Identify LED on a LWHEM hub
+await client.identify_whem(whem_id)
+```
+
+## Energy History
+
+Energy history endpoints return consumption data for all devices in a residence.
+Data is keyed by hub ID, then by breaker position and CT channel.
+
+```python
+# Daily energy (hourly data points)
+day = await client.get_energy_for_day(
+    residence_id=713744,
+    start_day="2026-02-16",
+    timezone="America/Los_Angeles",
+)
+
+# Weekly energy (daily data points for 7 days)
+week = await client.get_energy_for_week(
+    residence_id=713744,
+    start_day="2026-02-17",
+    timezone="America/Los_Angeles",
+)
+
+# Monthly energy (daily data points for billing month)
+month = await client.get_energy_for_month(
+    residence_id=713744,
+    billing_day_in_month="2026-02-28",
+    timezone="America/Los_Angeles",
+)
+
+# Yearly energy (monthly data points for 12 months)
+year = await client.get_energy_for_year(
+    residence_id=713744,
+    billing_day_in_end_month="2026-02-16",
+    timezone="America/Los_Angeles",
+)
+
+# Response structure:
+# {
+#   "<hub_id>": {
+#     "residentialBreakers": {"<position>": [{x, timestamp, energyConsumption, totalCost, ...}]},
+#     "iotCts": {"<channel>": [...]},
+#     "totals": [...]
+#   },
+#   "totals": [...]  # residence-level totals
+# }
+```
+
+## Firmware Check
+
+```python
+# Check for available firmware updates
+firmware = await client.check_firmware(
+    app_id="LWHEM",
+    model="AZ",
+    serial="1000_003D_5D58",
+    model_type="IotWhem",
+)
+# Returns list of firmware objects with version, fileUrl, signature, hash, size, notes
+for fw in firmware:
+    print(f"v{fw['version']}: {fw['fileUrl']}")
+```
+
+
+## License
+
+MIT

aioleviton-0.1.0/README.md

@@ -0,0 +1,158 @@
+# aioleviton
+
+Async Python client for the Leviton My Leviton cloud API.
+
+Supports LWHEM and DAU/LDATA Smart Load Centers with WebSocket real-time push and REST API fallback.
+
+## Features
+
+- Pure `asyncio` with `aiohttp` -- no blocking calls
+- Accepts an injected `aiohttp.ClientSession` for connection pooling
+- WebSocket real-time push notifications with automatic subscription management
+- Full REST API coverage: authentication, device discovery, breaker control, energy history
+- Typed data models with PEP 561 `py.typed` marker
+- Support for both hub types: LWHEM (`IotWhem`) and DAU/LDATA (`ResidentialBreakerPanel`)
+- Two-factor authentication (2FA) support
+
+## Installation
+
+```bash
+pip install aioleviton
+```
+
+## Quick Start
+
+```python
+import aiohttp
+from aioleviton import LevitonClient, LevitonWebSocket
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        # Authenticate
+        client = LevitonClient(session)
+        auth = await client.login("user@example.com", "password")
+
+        # Discover devices
+        permissions = await client.get_permissions()
+        for perm in permissions:
+            if perm.residential_account_id:
+                residences = await client.get_residences(perm.residential_account_id)
+                for residence in residences:
+                    whems = await client.get_whems(residence.id)
+                    panels = await client.get_panels(residence.id)
+
+        # Get breakers for a LWHEM hub
+        for whem in whems:
+            breakers = await client.get_whem_breakers(whem.id)
+            cts = await client.get_cts(whem.id)
+
+        # Connect WebSocket for real-time updates
+        ws = LevitonWebSocket(
+            session=session,
+            token=auth.token,
+            user_id=auth.user_id,
+            user=auth.user,
+            token_created=auth.created,
+            token_ttl=auth.ttl,
+        )
+        await ws.connect()
+
+        # Subscribe to a hub (delivers all child breaker/CT updates)
+        await ws.subscribe("IotWhem", whem.id)
+
+        # Handle notifications
+        ws.on_notification(lambda data: print("Update:", data))
+```
+
+## Supported Devices
+
+| Device | API Model | Hub Type |
+|--------|-----------|----------|
+| LWHEM (Whole Home Energy Module) | `IotWhem` | Wi-Fi hub |
+| DAU / LDATA (Data Acquisition Unit) | `ResidentialBreakerPanel` | Wi-Fi hub |
+| Smart Breaker Gen 1 (trip only) | `ResidentialBreaker` | Child of LWHEM or DAU |
+| Smart Breaker Gen 2 (on/off) | `ResidentialBreaker` | Child of LWHEM or DAU |
+| Current Transformer (CT) | `IotCt` | Child of LWHEM only |
+| LSBMA Add-on CT | `ResidentialBreaker` | Virtual composite |
+
+## Breaker Control
+
+```python
+# Trip a Gen 1 breaker (cannot turn back on remotely)
+await client.trip_breaker(breaker_id)
+
+# Turn on/off a Gen 2 breaker
+await client.turn_on_breaker(breaker_id)
+await client.turn_off_breaker(breaker_id)
+
+# Blink LED on a breaker
+await client.blink_led(breaker_id)
+
+# Identify LED on a LWHEM hub
+await client.identify_whem(whem_id)
+```
+
+## Energy History
+
+Energy history endpoints return consumption data for all devices in a residence.
+Data is keyed by hub ID, then by breaker position and CT channel.
+
+```python
+# Daily energy (hourly data points)
+day = await client.get_energy_for_day(
+    residence_id=713744,
+    start_day="2026-02-16",
+    timezone="America/Los_Angeles",
+)
+
+# Weekly energy (daily data points for 7 days)
+week = await client.get_energy_for_week(
+    residence_id=713744,
+    start_day="2026-02-17",
+    timezone="America/Los_Angeles",
+)
+
+# Monthly energy (daily data points for billing month)
+month = await client.get_energy_for_month(
+    residence_id=713744,
+    billing_day_in_month="2026-02-28",
+    timezone="America/Los_Angeles",
+)
+
+# Yearly energy (monthly data points for 12 months)
+year = await client.get_energy_for_year(
+    residence_id=713744,
+    billing_day_in_end_month="2026-02-16",
+    timezone="America/Los_Angeles",
+)
+
+# Response structure:
+# {
+#   "<hub_id>": {
+#     "residentialBreakers": {"<position>": [{x, timestamp, energyConsumption, totalCost, ...}]},
+#     "iotCts": {"<channel>": [...]},
+#     "totals": [...]
+#   },
+#   "totals": [...]  # residence-level totals
+# }
+```
+
+## Firmware Check
+
+```python
+# Check for available firmware updates
+firmware = await client.check_firmware(
+    app_id="LWHEM",
+    model="AZ",
+    serial="1000_003D_5D58",
+    model_type="IotWhem",
+)
+# Returns list of firmware objects with version, fileUrl, signature, hash, size, notes
+for fw in firmware:
+    print(f"v{fw['version']}: {fw['fileUrl']}")
+```
+
+
+## License
+
+MIT

aioleviton-0.1.0/aioleviton/__init__.py

@@ -0,0 +1,33 @@
+"""Async Python client for the Leviton My Leviton cloud API."""
+
+__version__ = "0.1.0"
+
+from .client import LevitonClient
+from .exceptions import (
+    LevitonAuthError,
+    LevitonConnectionError,
+    LevitonError,
+    LevitonInvalidCode,
+    LevitonTokenExpired,
+    LevitonTwoFactorRequired,
+)
+from .models import AuthToken, Breaker, Ct, Panel, Permission, Residence, Whem
+from .websocket import LevitonWebSocket
+
+__all__ = [
+    "AuthToken",
+    "Breaker",
+    "Ct",
+    "LevitonAuthError",
+    "LevitonClient",
+    "LevitonConnectionError",
+    "LevitonError",
+    "LevitonInvalidCode",
+    "LevitonTokenExpired",
+    "LevitonTwoFactorRequired",
+    "LevitonWebSocket",
+    "Panel",
+    "Permission",
+    "Residence",
+    "Whem",
+]