span-panel-api 0.1.0__tar.gz

span_panel_api-0.1.0/LICENSE

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

span_panel_api-0.1.0/PKG-INFO

@@ -0,0 +1,457 @@
+Metadata-Version: 2.3
+Name: span-panel-api
+Version: 0.1.0
+Summary: A client library for SPAN Panel API
+Author: SpanPanel
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: attrs (>=22.2.0)
+Requires-Dist: click (>=8.0.0,<9.0.0)
+Requires-Dist: httpx (>=0.20.0,<0.29.0)
+Requires-Dist: python-dateutil (>=2.8.0,<3.0.0)
+Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
+Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
+Description-Content-Type: text/markdown
+
+# SPAN Panel OpenAPI Client
+
+A Python client library for accessing the SPAN Panel API.
+
+
+## Installation
+
+```bash
+pip install span-panel-api
+```
+
+## Usage Patterns
+
+The client supports two usage patterns depending on your use case:
+
+### Context Manager Pattern (Recommended for Scripts)
+
+**Best for**: Scripts, one-off operations, short-lived applications
+
+```python
+import asyncio
+from span_panel_api import SpanPanelClient
+
+async def main():
+    # Context manager automatically handles connection lifecycle
+    async with SpanPanelClient("192.168.1.100") as client:
+        # Authenticate
+        auth = await client.authenticate("my-script", "SPAN Control Script")
+
+        # Get panel status (no auth required)
+        status = await client.get_status()
+        print(f"Panel: {status.system.manufacturer}")
+
+        # Get circuits (requires auth)
+        circuits = await client.get_circuits()
+        for circuit_id, circuit in circuits.circuits.additional_properties.items():
+            print(f"{circuit.name}: {circuit.instant_power_w}W")
+
+        # Control a circuit
+        await client.set_circuit_relay("circuit-1", "OPEN")
+        await client.set_circuit_priority("circuit-1", "MUST_HAVE")
+
+    # Client is automatically closed when exiting context
+
+asyncio.run(main())
+```
+
+### Long-Lived Pattern (Services and Integrations)
+
+**Best for**: Long-running services, persistent connections, integration platforms
+
+```python
+import asyncio
+from span_panel_api import SpanPanelClient
+
+class SpanPanelIntegration:
+    """Example long-running service integration pattern."""
+
+    def __init__(self, host: str):
+        # Create client but don't use context manager
+        self.client = SpanPanelClient(host)
+        self._authenticated = False
+
+    async def setup(self) -> None:
+        """Initialize the integration (called once)."""
+        try:
+            # Authenticate once during setup
+            await self.client.authenticate("my-service", "Panel Integration Service")
+            self._authenticated = True
+        except Exception as e:
+            await self.client.close()  # Clean up on setup failure
+            raise
+
+    async def update_data(self) -> dict:
+        """Update all data (called periodically by coordinator)."""
+        if not self._authenticated:
+            await self.client.authenticate("my-service", "Panel Integration Service")
+            self._authenticated = True
+
+        try:
+            # Get all data in one update cycle
+            status = await self.client.get_status()
+            panel_state = await self.client.get_panel_state()
+            circuits = await self.client.get_circuits()
+            storage = await self.client.get_storage_soe()
+
+            return {
+                "status": status,
+                "panel": panel_state,
+                "circuits": circuits,
+                "storage": storage
+            }
+        except Exception:
+            self._authenticated = False  # Reset auth on error
+            raise
+
+    async def set_circuit_priority(self, circuit_id: str, priority: str) -> None:
+        """Set circuit priority (called by service)."""
+        if not self._authenticated:
+            await self.client.authenticate("my-service", "Panel Integration Service")
+            self._authenticated = True
+
+        await self.client.set_circuit_priority(circuit_id, priority)
+
+    async def cleanup(self) -> None:
+        """Cleanup when integration is unloaded."""
+        await self.client.close()
+
+# Usage in long-running service
+async def main():
+    integration = SpanPanelIntegration("192.168.1.100")
+
+    try:
+        await integration.setup()
+
+        # Simulate coordinator updates
+        for i in range(10):
+            data = await integration.update_data()
+            print(f"Update {i}: {len(data['circuits'].circuits.additional_properties)} circuits")
+            await asyncio.sleep(30)  # Service typically updates every 30 seconds
+
+    finally:
+        await integration.cleanup()
+
+asyncio.run(main())
+```
+
+### Manual Pattern (Advanced Usage)
+
+**Best for**: Custom connection management, special requirements
+
+```python
+import asyncio
+from span_panel_api import SpanPanelClient
+
+async def manual_example():
+    """Manual client lifecycle management."""
+    client = SpanPanelClient("192.168.1.100")
+
+    try:
+        # Manually authenticate
+        await client.authenticate("manual-app", "Manual Application")
+
+        # Do work
+        status = await client.get_status()
+        circuits = await client.get_circuits()
+
+        print(f"Found {len(circuits.circuits.additional_properties)} circuits")
+
+    except Exception as e:
+        print(f"Error: {e}")
+    finally:
+        # IMPORTANT: Always close the client to free resources
+        await client.close()
+
+asyncio.run(manual_example())
+```
+
+## When to Use Each Pattern
+
+| Pattern | Use Case | Pros | Cons |
+|---------|----------|------|------|
+| **Context Manager** | Scripts, one-off tasks, testing | Automatic cleanup • Exception safe • Simple code | Creates/destroys connection each time • Not efficient for frequent calls |
+| **Long-Lived** | Services, daemons, integration platforms | Efficient connection reuse • Better performance • Authentication persistence | Manual lifecycle management • Must handle cleanup |
+| **Manual** | Custom requirements, debugging | Full control • Custom error handling | Must remember to call close() • More error-prone |
+
+## Error Handling
+
+The client provides error categorization for different retry strategies:
+
+### Exception Types
+
+```python
+from span_panel_api.exceptions import (
+    SpanPanelError,           # Base exception
+    SpanPanelAPIError,        # General API errors
+    SpanPanelAuthError,       # 401/403 - need re-authentication
+    SpanPanelConnectionError, # Network connectivity issues
+    SpanPanelTimeoutError,    # Request timeouts
+    SpanPanelRetriableError,  # 502/503/504 - temporary issues, SHOULD retry
+    SpanPanelServerError,     # 500 - application bugs, DO NOT retry
+)
+```
+
+### HTTP Error Code Mapping
+
+| Status Code | Exception | Retry? | Description | Action |
+|-------------|-----------|--------|-------------|--------|
+| **Authentication Errors** |
+| 401, 403    | `SpanPanelAuthError` | Once (after re-auth) | Authentication required/failed | Re-authenticate and retry once |
+| **Non-Retriable Server Errors** |
+| 500         | `SpanPanelServerError` | **NO** | Internal server error (SPAN bug) | Show error, do not retry |
+| **Retriable Server Errors** |
+| 502         | `SpanPanelRetriableError` | Yes | Bad Gateway (proxy error) | Retry with exponential backoff |
+| 503         | `SpanPanelRetriableError` | Yes | Service Unavailable | Retry with exponential backoff |
+| 504         | `SpanPanelRetriableError` | Yes | Gateway Timeout | Retry with exponential backoff |
+| **Other HTTP Errors** |
+| 404, 400, etc | `SpanPanelAPIError` | Case by case | Client/request errors | Check request parameters |
+| **Network Errors** |
+| Connection failures | `SpanPanelConnectionError` | Yes | Network connectivity issues | Retry with backoff |
+| Timeouts | `SpanPanelTimeoutError` | Yes | Request timed out | Retry with backoff |
+
+### Retry Strategy
+
+```python
+async def example_request_with_retry():
+    """Example showing appropriate error handling."""
+    try:
+        return await client.get_circuits()
+    except SpanPanelAuthError:
+        # Re-authenticate and retry once
+        await client.authenticate("my-app", "My Application")
+        return await client.get_circuits()
+    except SpanPanelRetriableError as e:
+        # Temporary server issues - should retry with backoff
+        # 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout
+        logger.warning(f"Retriable error {e.status_code}, will retry: {e}")
+        raise  # Let retry logic handle the retry
+    except SpanPanelServerError as e:
+        # Application bugs on SPAN side - DO NOT retry
+        # 500 Internal Server Error (SPAN Panel bug, not your fault!)
+        logger.error(f"Server error {e.status_code}, not retrying: {e}")
+        raise  # Show notification but don't waste resources retrying
+    except (SpanPanelConnectionError, SpanPanelTimeoutError):
+        # Network issues - should retry
+        raise
+```
+
+### Exception Handling
+
+The client configures the underlying OpenAPI client with `raise_on_unexpected_status=True`, ensuring that HTTP errors (especially 500 responses) are converted to appropriate exceptions rather than being silently ignored.
+
+## API Reference
+
+### Client Initialization
+
+```python
+client = SpanPanelClient(
+    host="192.168.1.100",    # Required: SPAN Panel IP
+    port=80,                 # Optional: default 80
+    timeout=30.0,            # Optional: request timeout
+    use_ssl=False            # Optional: HTTPS (usually False for local)
+)
+```
+
+### Authentication
+
+```python
+# Register a new API client (one-time setup)
+auth = await client.authenticate(
+    name="my-integration",           # Required: client name
+    description="My Application"  # Optional: description
+)
+# Token is stored and used for subsequent requests
+```
+
+### Panel Information
+
+```python
+# System status (no authentication required)
+status = await client.get_status()
+print(f"System: {status.system}")
+print(f"Network: {status.network}")
+
+# Detailed panel state (requires authentication)
+panel = await client.get_panel_state()
+print(f"Grid power: {panel.instant_grid_power_w}W")
+print(f"Main relay: {panel.main_relay_state}")
+
+# Battery storage information
+storage = await client.get_storage_soe()
+print(f"Battery SOE: {storage.soe * 100:.1f}%")
+print(f"Max capacity: {storage.max_energy_kwh}kWh")
+```
+
+### Circuit Control
+
+```python
+# Get all circuits
+circuits = await client.get_circuits()
+for circuit_id, circuit in circuits.circuits.additional_properties.items():
+    print(f"Circuit {circuit_id}: {circuit.name}")
+    print(f"  Power: {circuit.instant_power_w}W")
+    print(f"  Relay: {circuit.relay_state}")
+    print(f"  Priority: {circuit.priority}")
+
+# Control circuit relay (OPEN/CLOSED)
+await client.set_circuit_relay("circuit-1", "OPEN")   # Turn off
+await client.set_circuit_relay("circuit-1", "CLOSED") # Turn on
+
+# Set circuit priority
+await client.set_circuit_priority("circuit-1", "MUST_HAVE")
+await client.set_circuit_priority("circuit-1", "NICE_TO_HAVE")
+```
+
+## Timeout and Retry Control
+
+The SPAN Panel API client provides timeout and retry configuration:
+
+- `timeout` (float, default: 30.0): The maximum time (in seconds) to wait for a response from the panel for each attempt.
+- `retries` (int, default: 0): The number of times to retry a failed request due to network or retriable server errors. `retries=0` means no retries (1 total attempt), `retries=1` means 1 retry (2 total attempts), etc.
+- `retry_timeout` (float, default: 0.5): The base wait time (in seconds) between retries, with exponential backoff.
+- `retry_backoff_multiplier` (float, default: 2.0): The multiplier for exponential backoff between retries.
+
+### Example Usage
+
+```python
+# No retries (default, fast feedback)
+client = SpanPanelClient("192.168.1.100", timeout=10.0)
+
+# Add retries for production
+client = SpanPanelClient("192.168.1.100", timeout=10.0, retries=2, retry_timeout=1.0)
+
+# Full retry configuration
+client = SpanPanelClient(
+    "192.168.1.100",
+    timeout=10.0,
+    retries=3,
+    retry_timeout=0.5,
+    retry_backoff_multiplier=2.0
+)
+
+# Change retry settings at runtime
+client.retries = 3
+client.retry_timeout = 2.0
+client.retry_backoff_multiplier = 1.5
+```
+
+### What does 'retries' mean?
+
+| retries | Total Attempts | Description         |
+|---------|---------------|---------------------|
+| 0       | 1             | No retries (default) |
+| 1       | 2             | 1 retry             |
+| 2       | 3             | 2 retries           |
+
+Retry and timeout settings can be queried and changed at runtime.
+
+## Development Setup
+
+### Prerequisites
+- Python 3.12+ (SPAN Panel requires Python 3.12+)
+- [Poetry](https://python-poetry.org/) for dependency management
+
+### Installation
+
+```bash
+# Clone and install
+git clone <repository code URL>
+cd span-panel-api
+poetry install
+poetry env activate
+
+# Run tests
+poetry run pytest
+
+# Check coverage
+python scripts/coverage.py
+```
+
+### Project Structure
+
+```
+span_openapi/
+├── src/span_panel_api/        # Main client library
+│   ├── client.py              # SpanPanelClient (high-level wrapper)
+│   ├── exceptions.py          # Exception hierarchy
+│   ├── const.py               # HTTP status constants
+│   └── generated_client/      # Auto-generated OpenAPI client
+├── tests/                     # test suite
+├── scripts/coverage.py        # Coverage checking utility
+├── openapi.json              # SPAN Panel OpenAPI specification
+└── pyproject.toml            # Poetry configuration
+```
+
+
+
+## Advanced Usage
+
+### SSL Configuration
+
+```python
+# For panels that support SSL locally
+# Note: We do not currently observe panels supporting SSL for local access
+client = SpanPanelClient(
+    host="span-panel.local",
+    use_ssl=True,
+    port=443
+)
+```
+
+### Timeout Configuration
+
+```python
+# Custom timeout for slow networks
+client = SpanPanelClient(
+    host="192.168.1.100",
+    timeout=60.0  # 60 second timeout
+)
+```
+
+## Testing and Coverage
+
+```bash
+# Run full test suite
+poetry run pytest
+
+# Generate coverage report
+python scripts/coverage.py --full
+
+# Run just context manager tests
+poetry run pytest tests/test_context_manager.py -v
+
+# Check coverage meets threshold
+python scripts/coverage.py --check --threshold 95
+
+# Run with coverage
+poetry run pytest --cov=span_panel_api tests/
+```
+
+## Contributing
+
+1. Get `openapi.json`  SPAN Panel API specs
+
+    (for example via REST Client extension)
+
+    GET <https://span-panel-ip/api/v1/openapi.json>
+
+2. Regenerate client: `poetry run python generate_client.py`
+3. Update wrapper client in `src/span_panel_api/client.py` if needed
+4. Add tests for new functionality
+5. Update this README if adding new features
+
+## License
+
+MIT License - see LICENSE file for details.
+