Metadata-Version: 2.4
Name: generac-pwrview
Version: 0.1.0
Summary: Async Python client for Generac PWRview / Neurio energy monitors
Author: Kevin Mills
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/W7RZL/generac-pwrview-python
Project-URL: Repository, https://github.com/W7RZL/generac-pwrview-python
Project-URL: Issues, https://github.com/W7RZL/generac-pwrview-python/issues
Keywords: generac,pwrview,neurio,energy,iot,home-assistant
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: aioresponses>=0.7; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# generac-pwrview

Async Python client for [Generac PWRview](https://www.generac.com/) (formerly Neurio) energy monitors.

Supports both the cloud API and direct local device access over your network.

## Features

- **Async-first** — built on `aiohttp`, no blocking calls
- **Cloud API** — OAuth2 authentication, live samples, energy stats, full channel data
- **Local API** — direct device polling with no cloud account required
- **Typed** — full type hints with `py.typed` (PEP 561)
- **Session injection** — pass your own `aiohttp.ClientSession` or let the client manage one

## Installation

```bash
pip install generac-pwrview
```

## Usage

### Cloud API

```python
import aiohttp
from generac_pwrview import PWRviewClient

async with aiohttp.ClientSession() as session:
    client = PWRviewClient(
        api_key="your_api_key",
        api_secret="your_api_secret",
        session=session,
    )

    # Discover sensors on your account
    user_info = await client.get_user_information()
    sensor = user_info.locations[0].sensors[0]
    print(f"Sensor: {sensor.serial_number} at {sensor.ip_address}")

    # Get current power readings
    live = await client.get_live_sample(sensor.sensor_id)
    print(f"Consumption: {live.consumption_power} W")
    print(f"Generation:  {live.generation_power} W")
    print(f"Net:         {live.net_power} W")

    # Get today's energy stats
    stats = await client.get_stats(sensor.sensor_id, start, "days", end)

    # Get full samples with voltage and phase data
    samples = await client.get_samples(
        sensor.sensor_id, start, "hours", end, full=True
    )
```

### Local API

No cloud account needed — connect directly to the device on your network.

```python
import aiohttp
from generac_pwrview import PWRviewLocalClient

async with aiohttp.ClientSession() as session:
    client = PWRviewLocalClient(host="192.168.1.100", session=session)
    sample = await client.get_current_sample()

    for channel in sample.channels:
        print(f"[{channel.channel_type}] {channel.power} W @ {channel.voltage} V")
```

### Standalone (no session injection)

```python
from generac_pwrview import PWRviewClient

async with PWRviewClient(api_key="...", api_secret="...") as client:
    user_info = await client.get_user_information()
```

## API Reference

### `PWRviewClient` (cloud)

| Method | Description |
|--------|-------------|
| `get_user_information()` | Discover sensors and locations on your account |
| `get_live_sample(sensor_id)` | Current power and energy readings |
| `get_stats(sensor_id, start, granularity, end)` | Aggregated energy statistics |
| `get_samples(sensor_id, start, granularity, end, full=False)` | Historical samples with optional channel/voltage data |

### `PWRviewLocalClient` (local)

| Method | Description |
|--------|-------------|
| `get_current_sample()` | Real-time reading from the device |

### Exceptions

| Exception | Meaning |
|-----------|---------|
| `PWRviewError` | Base exception |
| `PWRviewConnectionError` | Cannot reach the API or device |
| `PWRviewAuthError` | Invalid or expired credentials |
| `PWRviewResponseError` | Unexpected API response |

## Getting API credentials

1. Go to https://my.neur.io/#settings/applications/register
2. Create a new application (homepage and callback URLs are optional)
3. Note your API key and secret

## Attribution

This library is a modernized fork of [neurio-python](https://github.com/jordanh/neurio-python) by Jordan Husney. The original library provided the foundation for understanding the Neurio/Generac API. This version has been rewritten with async support, type hints, and structured response models.

## License

Apache License 2.0 — see [LICENSE](./LICENSE) for details.

Original work copyright 2015, 2016 Jordan Husney.
