dompower 0.1.0__tar.gz

dompower-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run ruff linting
+        run: ruff check .
+
+      - name: Run ruff formatting check
+        run: ruff format --check .
+
+      - name: Run mypy type checking
+        run: mypy dompower
+
+      - name: Run pytest
+        run: pytest tests/ -v --tb=short

dompower-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,125 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Target PyPI environment'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run ruff linting
+        run: ruff check .
+
+      - name: Run ruff formatting check
+        run: ruff format --check .
+
+      - name: Run mypy type checking
+        run: mypy dompower
+
+      - name: Run pytest
+        run: pytest tests/ -v
+
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 5
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/dompower
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dompower
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dompower-0.1.0/.gitignore

@@ -0,0 +1,95 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ruff
+.ruff_cache/
+
+# Token files (sensitive)
+tokens.json
+*.tokens
+
+# Cookies and session data
+cookies.txt
+cookies*.txt
+
+# Log files with sensitive data
+*-log-flow.txt
+output*.txt
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local development
+*.local
+.env.local

dompower-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        files: ^dompower/
+        additional_dependencies:
+          - aiohttp
+          - openpyxl

dompower-0.1.0/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+dompower is an async Python client library for the Dominion Energy API. It retrieves 30-minute interval electricity usage data and is designed for integration with Home Assistant.
+
+## Commands
+
+```bash
+# Install dependencies (uses uv)
+uv sync --dev
+
+# Run tests
+uv run pytest
+
+# Run a single test
+uv run pytest tests/test_file.py::test_function_name
+
+# Type checking
+uv run mypy dompower
+
+# Linting
+uv run ruff check dompower
+
+# Format code
+uv run ruff format dompower
+```
+
+## Architecture
+
+### Core Components
+
+- **`client.py`** - `DompowerClient`: Main API client. Handles authenticated requests, token refresh on 401, and parsing API responses. Entry point for all usage data fetching.
+
+- **`auth.py`** - `TokenManager`: Manages access/refresh token lifecycle. Tokens expire every 30 minutes; automatically refreshes and invokes callback to persist new tokens.
+
+- **`gigya_auth.py`** - `GigyaAuthenticator`: Handles the multi-step Gigya SSO authentication flow with two-factor authentication (TFA) support. Used for initial login (not token refresh).
+
+### Authentication Flow
+
+1. Initial auth requires manual browser login (CAPTCHA protected) OR programmatic Gigya flow with TFA
+2. Both `access_token` and `refresh_token` are needed for API calls
+3. Tokens rotate on every refresh (both change) - client notifies via `token_update_callback`
+4. Access tokens expire in 30 minutes; refresh tokens expire after extended inactivity
+
+### Data Models (`models.py`)
+
+Key frozen dataclasses:
+- `IntervalUsageData` - 30-minute consumption data (timestamp, consumption, unit)
+- `TokenPair` - Access/refresh token pair
+- `BillForecast` / `BillPeriodData` - Billing data with `derived_rate` property for $/kWh
+- `CustomerInfo` / `AccountInfo` / `MeterDevice` - Account hierarchy
+- `GigyaSession` / `TFATarget` - TFA authentication state
+
+### Exception Hierarchy (`exceptions.py`)
+
+```
+DompowerError
+├── AuthenticationError
+│   ├── InvalidAuthError
+│   ├── TokenExpiredError
+│   ├── BrowserAuthRequiredError
+│   └── GigyaError
+│       ├── InvalidCredentialsError
+│       ├── TFARequiredError
+│       ├── TFAVerificationError
+│       └── TFAExpiredError
+├── CannotConnectError
+└── ApiError
+    └── RateLimitError
+```
+
+## Testing
+
+- Uses pytest-asyncio with `asyncio_mode = "auto"`
+- Uses aresponses for mocking aiohttp requests
+- Test fixtures in `tests/conftest.py`
+
+## Code Style
+
+- Python 3.12+ with strict mypy
+- Ruff for linting (includes isort, pycodestyle, flake8-bugbear, flake8-bandit)
+- All public classes/methods have docstrings
+- Async methods prefixed with `async_`
+- Private methods prefixed with `_`