hyponcloud 0.1.0__tar.gz

hyponcloud-0.1.0/LICENSE

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

hyponcloud-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include hyponcloud *.py py.typed

hyponcloud-0.1.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: hyponcloud
+Version: 0.1.0
+Summary: Python library for Hypontech Cloud API
+Author-email: jcisio <jcisio@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jcisio/hyponcloud
+Project-URL: Repository, https://github.com/jcisio/hyponcloud
+Project-URL: Issues, https://github.com/jcisio/hyponcloud/issues
+Keywords: hypontech,solar,inverter,api,async
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Hypontech Cloud API Python Library
+
+A Python library for interacting with the Hypontech Cloud API for solar inverter monitoring.
+
+## Features
+
+- Async/await support using aiohttp
+- Get plant overview data (power, energy production, device status)
+- Get plant list
+- Automatic token management and refresh
+- Built-in retry logic for rate limiting
+- Type hints for better IDE support
+- Comprehensive error handling
+
+## Installation
+
+```bash
+pip install hyponcloud
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import asyncio
+from hyponcloud import HyponCloud
+
+async def main():
+    # Create client with your credentials
+    async with HyponCloud("your_username", "your_password") as client:
+        # Connect and authenticate
+        if await client.connect():
+            # Get overview data
+            overview = await client.get_overview()
+            print(f"Current power: {overview.power}W")
+            print(f"Today's energy: {overview.e_today}kWh")
+            print(f"Total energy: {overview.e_total}kWh")
+
+            # Get plant list
+            plants = await client.get_list()
+            print(f"Number of plants: {len(plants)}")
+
+asyncio.run(main())
+```
+
+### Using with Custom aiohttp Session
+
+```python
+import aiohttp
+from hyponcloud import HyponCloud
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = HyponCloud("your_username", "your_password", session=session)
+
+        if await client.connect():
+            overview = await client.get_overview()
+            print(f"Power: {overview.power}W")
+
+asyncio.run(main())
+```
+
+### Error Handling
+
+```python
+from hyponcloud import (
+    HyponCloud,
+    AuthenticationError,
+    ConnectionError,
+    RateLimitError,
+)
+
+async def main():
+    try:
+        async with HyponCloud("username", "password") as client:
+            await client.connect()
+            overview = await client.get_overview()
+            print(f"Power: {overview.power}W")
+
+    except AuthenticationError as e:
+        print(f"Authentication failed: {e}")
+    except RateLimitError as e:
+        print(f"Rate limit exceeded: {e}")
+    except ConnectionError as e:
+        print(f"Connection error: {e}")
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### HyponCloud
+
+Main client class for interacting with the Hypontech Cloud API.
+
+#### Methods
+
+##### `__init__(username: str, password: str, session: aiohttp.ClientSession | None = None)`
+
+Initialize the client.
+
+- `username`: Your Hypontech Cloud username
+- `password`: Your Hypontech Cloud password
+- `session`: Optional aiohttp ClientSession. If not provided, one will be created automatically.
+
+##### `async connect() -> bool`
+
+Authenticate with the API and retrieve access token.
+
+**Returns:** `True` if successful, `False` otherwise
+
+**Raises:**
+- `AuthenticationError`: Invalid credentials
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async get_overview(retries: int = 3) -> OverviewData`
+
+Get plant overview data including power generation and device status.
+
+**Parameters:**
+- `retries`: Number of retry attempts on failure (default: 3)
+
+**Returns:** `OverviewData` object
+
+**Raises:**
+- `AuthenticationError`: Authentication required
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async get_list(retries: int = 3) -> list[dict]`
+
+Get list of plants associated with the account.
+
+**Parameters:**
+- `retries`: Number of retry attempts on failure (default: 3)
+
+**Returns:** List of plant dictionaries
+
+**Raises:**
+- `AuthenticationError`: Authentication required
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async close() -> None`
+
+Close the aiohttp session (only if created by the library).
+
+### OverviewData
+
+Data class containing plant overview information.
+
+#### Attributes
+
+- `capacity` (float): Plant capacity
+- `capacity_company` (str): Capacity unit (e.g., "KW")
+- `power` (int): Current power generation in watts
+- `company` (str): Power unit (e.g., "W")
+- `percent` (int): Percentage value
+- `e_today` (float): Today's energy production in kWh
+- `e_total` (float): Total lifetime energy production in kWh
+- `fault_dev_num` (int): Number of faulty devices
+- `normal_dev_num` (int): Number of normal devices
+- `offline_dev_num` (int): Number of offline devices
+- `wait_dev_num` (int): Number of devices waiting
+- `total_co2` (int): Total CO2 savings
+- `total_tree` (float): Equivalent trees planted
+
+### PlantData
+
+Data class containing individual plant information.
+
+#### Attributes
+
+- `city` (str): Plant location city
+- `country` (str): Plant location country
+- `e_today` (float): Today's energy production
+- `e_total` (float): Total energy production
+- `eid` (int): Equipment ID
+- `kwhimp` (int): kWh import
+- `micro` (int): Micro inverter count
+- `plant_id` (str): Unique plant identifier
+- `plant_name` (str): Plant name
+- `plant_type` (str): Plant type
+- `power` (int): Current power
+- `status` (str): Plant status
+
+### Exceptions
+
+- `HyponCloudError`: Base exception for all library errors
+- `AuthenticationError`: Authentication failed (invalid credentials)
+- `ConnectionError`: Connection to API failed
+- `RateLimitError`: API rate limit exceeded
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/jcisio/hyponcloud.git
+cd hyponcloud
+
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+ruff check .
+ruff format .
+```
+
+### Type Checking
+
+```bash
+mypy hyponcloud
+```
+
+## Requirements
+
+- Python 3.11+
+- aiohttp 3.8.0+
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Disclaimer
+
+This library is not officially associated with or endorsed by Hypontech. Use at your own risk.
+
+## Support
+
+For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/jcisio/hyponcloud).

hyponcloud-0.1.0/README.md

@@ -0,0 +1,247 @@
+# Hypontech Cloud API Python Library
+
+A Python library for interacting with the Hypontech Cloud API for solar inverter monitoring.
+
+## Features
+
+- Async/await support using aiohttp
+- Get plant overview data (power, energy production, device status)
+- Get plant list
+- Automatic token management and refresh
+- Built-in retry logic for rate limiting
+- Type hints for better IDE support
+- Comprehensive error handling
+
+## Installation
+
+```bash
+pip install hyponcloud
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import asyncio
+from hyponcloud import HyponCloud
+
+async def main():
+    # Create client with your credentials
+    async with HyponCloud("your_username", "your_password") as client:
+        # Connect and authenticate
+        if await client.connect():
+            # Get overview data
+            overview = await client.get_overview()
+            print(f"Current power: {overview.power}W")
+            print(f"Today's energy: {overview.e_today}kWh")
+            print(f"Total energy: {overview.e_total}kWh")
+
+            # Get plant list
+            plants = await client.get_list()
+            print(f"Number of plants: {len(plants)}")
+
+asyncio.run(main())
+```
+
+### Using with Custom aiohttp Session
+
+```python
+import aiohttp
+from hyponcloud import HyponCloud
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = HyponCloud("your_username", "your_password", session=session)
+
+        if await client.connect():
+            overview = await client.get_overview()
+            print(f"Power: {overview.power}W")
+
+asyncio.run(main())
+```
+
+### Error Handling
+
+```python
+from hyponcloud import (
+    HyponCloud,
+    AuthenticationError,
+    ConnectionError,
+    RateLimitError,
+)
+
+async def main():
+    try:
+        async with HyponCloud("username", "password") as client:
+            await client.connect()
+            overview = await client.get_overview()
+            print(f"Power: {overview.power}W")
+
+    except AuthenticationError as e:
+        print(f"Authentication failed: {e}")
+    except RateLimitError as e:
+        print(f"Rate limit exceeded: {e}")
+    except ConnectionError as e:
+        print(f"Connection error: {e}")
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### HyponCloud
+
+Main client class for interacting with the Hypontech Cloud API.
+
+#### Methods
+
+##### `__init__(username: str, password: str, session: aiohttp.ClientSession | None = None)`
+
+Initialize the client.
+
+- `username`: Your Hypontech Cloud username
+- `password`: Your Hypontech Cloud password
+- `session`: Optional aiohttp ClientSession. If not provided, one will be created automatically.
+
+##### `async connect() -> bool`
+
+Authenticate with the API and retrieve access token.
+
+**Returns:** `True` if successful, `False` otherwise
+
+**Raises:**
+- `AuthenticationError`: Invalid credentials
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async get_overview(retries: int = 3) -> OverviewData`
+
+Get plant overview data including power generation and device status.
+
+**Parameters:**
+- `retries`: Number of retry attempts on failure (default: 3)
+
+**Returns:** `OverviewData` object
+
+**Raises:**
+- `AuthenticationError`: Authentication required
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async get_list(retries: int = 3) -> list[dict]`
+
+Get list of plants associated with the account.
+
+**Parameters:**
+- `retries`: Number of retry attempts on failure (default: 3)
+
+**Returns:** List of plant dictionaries
+
+**Raises:**
+- `AuthenticationError`: Authentication required
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async close() -> None`
+
+Close the aiohttp session (only if created by the library).
+
+### OverviewData
+
+Data class containing plant overview information.
+
+#### Attributes
+
+- `capacity` (float): Plant capacity
+- `capacity_company` (str): Capacity unit (e.g., "KW")
+- `power` (int): Current power generation in watts
+- `company` (str): Power unit (e.g., "W")
+- `percent` (int): Percentage value
+- `e_today` (float): Today's energy production in kWh
+- `e_total` (float): Total lifetime energy production in kWh
+- `fault_dev_num` (int): Number of faulty devices
+- `normal_dev_num` (int): Number of normal devices
+- `offline_dev_num` (int): Number of offline devices
+- `wait_dev_num` (int): Number of devices waiting
+- `total_co2` (int): Total CO2 savings
+- `total_tree` (float): Equivalent trees planted
+
+### PlantData
+
+Data class containing individual plant information.
+
+#### Attributes
+
+- `city` (str): Plant location city
+- `country` (str): Plant location country
+- `e_today` (float): Today's energy production
+- `e_total` (float): Total energy production
+- `eid` (int): Equipment ID
+- `kwhimp` (int): kWh import
+- `micro` (int): Micro inverter count
+- `plant_id` (str): Unique plant identifier
+- `plant_name` (str): Plant name
+- `plant_type` (str): Plant type
+- `power` (int): Current power
+- `status` (str): Plant status
+
+### Exceptions
+
+- `HyponCloudError`: Base exception for all library errors
+- `AuthenticationError`: Authentication failed (invalid credentials)
+- `ConnectionError`: Connection to API failed
+- `RateLimitError`: API rate limit exceeded
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/jcisio/hyponcloud.git
+cd hyponcloud
+
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+ruff check .
+ruff format .
+```
+
+### Type Checking
+
+```bash
+mypy hyponcloud
+```
+
+## Requirements
+
+- Python 3.11+
+- aiohttp 3.8.0+
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Disclaimer
+
+This library is not officially associated with or endorsed by Hypontech. Use at your own risk.
+
+## Support
+
+For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/jcisio/hyponcloud).

hyponcloud-0.1.0/hyponcloud/__init__.py

@@ -0,0 +1,22 @@
+"""Hypontech Cloud API Python library."""
+
+from .client import HyponCloud
+from .exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    HyponCloudError,
+    RateLimitError,
+)
+from .models import OverviewData, PlantData
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HyponCloud",
+    "HyponCloudError",
+    "AuthenticationError",
+    "ConnectionError",
+    "RateLimitError",
+    "OverviewData",
+    "PlantData",
+]

hyponcloud-0.1.0/hyponcloud/client.py

@@ -0,0 +1,189 @@
+"""Hypontech Cloud API client."""
+
+import asyncio
+import logging
+from time import time
+
+import aiohttp
+
+from .exceptions import AuthenticationError, ConnectionError, RateLimitError
+from .models import OverviewData
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class HyponCloud:
+    """HyponCloud API client."""
+
+    def __init__(
+        self, username: str, password: str, session: aiohttp.ClientSession | None = None
+    ) -> None:
+        """Initialize the HyponCloud class.
+
+        Args:
+            username: The username for Hypon Cloud.
+            password: The password for Hypon Cloud.
+            session: Optional aiohttp client session. If not provided, a new one will be created.
+        """
+        self.base_url = "https://api.hypon.cloud/v2"
+        self.token_validity = 3600
+        self.timeout = aiohttp.ClientTimeout(total=10)
+
+        self._session = session
+        self._own_session = session is None
+        self.__username = username
+        self.__password = password
+        self.__token = ""
+        self.__token_expires_at = 0
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        if self._own_session:
+            self._session = aiohttp.ClientSession()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        if self._own_session and self._session:
+            await self._session.close()
+
+    async def close(self) -> None:
+        """Close the session if we own it."""
+        if self._own_session and self._session:
+            await self._session.close()
+
+    async def connect(self) -> bool:
+        """Connect to Hypon Cloud and retrieve token.
+
+        Returns:
+            True if connection successful, False otherwise.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+            ConnectionError: If connection to API fails.
+        """
+        if self.__token and self.__token_expires_at > time():
+            return True
+
+        if not self._session:
+            self._session = aiohttp.ClientSession()
+            self._own_session = True
+
+        url = f"{self.base_url}/login"
+        data = {"username": self.__username, "password": self.__password}
+
+        try:
+            async with self._session.post(
+                url, json=data, timeout=self.timeout
+            ) as response:
+                if response.status == 401:
+                    raise AuthenticationError("Invalid credentials")
+                if response.status == 429:
+                    raise RateLimitError(
+                        "Rate limit exceeded. Requests are being sent too fast."
+                    )
+                if response.status != 200:
+                    _LOGGER.warning(
+                        "Connection failed with status %s", response.status
+                    )
+                    return False
+
+                result = await response.json()
+                self.__token = result["data"]["token"]
+                self.__token_expires_at = int(time()) + self.token_validity
+                return True
+        except aiohttp.ClientError as e:
+            raise ConnectionError(f"Failed to connect to Hypon Cloud: {e}") from e
+        except KeyError as e:
+            raise AuthenticationError(
+                f"Invalid response from API, missing token: {e}"
+            ) from e
+
+    async def get_overview(self, retries: int = 3) -> OverviewData:
+        """Get plant overview.
+
+        Args:
+            retries: Number of retry attempts if request fails.
+
+        Returns:
+            OverviewData object containing plant overview information.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+            ConnectionError: If connection to API fails.
+        """
+        if not await self.connect():
+            return OverviewData()
+
+        url = f"{self.base_url}/plant/overview"
+        headers = {"authorization": f"Bearer {self.__token}"}
+
+        try:
+            async with self._session.get(
+                url, headers=headers, timeout=self.timeout
+            ) as response:
+                if response.status == 429:
+                    if retries > 0:
+                        await asyncio.sleep(10)
+                        return await self.get_overview(retries - 1)
+                    raise RateLimitError("Rate limit exceeded for overview endpoint")
+
+                if response.status != 200:
+                    if retries > 0:
+                        await asyncio.sleep(10)
+                        return await self.get_overview(retries - 1)
+                    raise ConnectionError(
+                        f"Failed to get plant overview: HTTP {response.status}"
+                    )
+
+                result = await response.json()
+                data = result["data"]
+                return OverviewData(**data)
+        except KeyError as e:
+            _LOGGER.error("Error parsing plant overview data: %s", e)
+            # Unknown error. Try again.
+            if retries > 0:
+                return await self.get_overview(retries - 1)
+            return OverviewData()
+        except aiohttp.ClientError as e:
+            raise ConnectionError(f"Failed to get plant overview: {e}") from e
+
+    async def get_list(self, retries: int = 3) -> list[dict]:
+        """Get plant list.
+
+        Args:
+            retries: Number of retry attempts if request fails.
+
+        Returns:
+            List of plant data dictionaries.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+            ConnectionError: If connection to API fails.
+        """
+        url = f"{self.base_url}/plant/list2?page=1&page_size=10&refresh=true"
+        headers = {"authorization": f"Bearer {self.__token}"}
+
+        try:
+            async with self._session.get(
+                url, headers=headers, timeout=self.timeout
+            ) as response:
+                if response.status == 429:
+                    if retries > 0:
+                        await asyncio.sleep(10)
+                        return await self.get_list(retries - 1)
+                    raise RateLimitError("Rate limit exceeded for plant list endpoint")
+
+                if response.status != 200:
+                    if retries > 0:
+                        await asyncio.sleep(10)
+                        return await self.get_list(retries - 1)
+
+                result = await response.json()
+                return result["data"]
+        except Exception as e:
+            _LOGGER.error("Error getting plant list: %s", e)
+            # Unknown error. Try again.
+            if retries > 0:
+                return await self.get_list(retries - 1)
+            raise ConnectionError(f"Failed to get plant list: {e}") from e

hyponcloud-0.1.0/hyponcloud/exceptions.py

@@ -0,0 +1,17 @@
+"""Exceptions for Hypontech Cloud API."""
+
+
+class HyponCloudError(Exception):
+    """Base exception for Hypontech Cloud API."""
+
+
+class AuthenticationError(HyponCloudError):
+    """Exception raised when authentication fails."""
+
+
+class ConnectionError(HyponCloudError):
+    """Exception raised when connection to API fails."""
+
+
+class RateLimitError(HyponCloudError):
+    """Exception raised when API rate limit is exceeded."""

hyponcloud-0.1.0/hyponcloud/models.py

@@ -0,0 +1,93 @@
+"""Data models for Hypontech Cloud API."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class OverviewData:
+    """Overview data class.
+
+    This class represents the overview data for a Hypon Cloud plant.
+    It contains information about the plant's capacity, power, energy production,
+    device status, and environmental impact.
+    """
+
+    capacity: float
+    capacity_company: str
+    power: int
+    company: str
+    percent: int
+    e_today: float
+    e_total: float
+    fault_dev_num: int
+    normal_dev_num: int
+    offline_dev_num: int
+    wait_dev_num: int
+    total_co2: int
+    total_tree: float
+
+    def __init__(self, **data) -> None:
+        """Initialize the OverviewData class with data from the API.
+
+        Args:
+            data: Dictionary containing overview data from the API.
+        """
+        # The data attribute needs to be set manually because the API
+        # may return more results than the existing data attributes.
+        self.capacity = data.get("capacity", 0.0)
+        self.capacity_company = data.get("capacity_company", "KW")
+        self.power = data.get("power", 0)
+        self.company = data.get("company", "W")
+        self.percent = data.get("percent", 0)
+        self.e_today = data.get("e_today", 0.0)
+        self.e_total = data.get("e_total", 0.0)
+        self.fault_dev_num = data.get("fault_dev_num", 0)
+        self.normal_dev_num = data.get("normal_dev_num", 0)
+        self.offline_dev_num = data.get("offline_dev_num", 0)
+        self.wait_dev_num = data.get("wait_dev_num", 0)
+        self.total_co2 = data.get("total_co2", 0)
+        self.total_tree = data.get("total_tree", 0.0)
+
+
+@dataclass
+class PlantData:
+    """Plant data class.
+
+    This class represents the data for a Hypon Cloud plant.
+    It contains information about the plant's location, energy production,
+    identifiers, and status.
+    """
+
+    city: str
+    country: str
+    e_today: float
+    e_total: float
+    eid: int
+    kwhimp: int
+    micro: int
+    plant_id: str
+    plant_name: str
+    plant_type: str
+    power: int
+    status: str
+
+    def __init__(self, **data) -> None:
+        """Initialize the PlantData class with data from the API.
+
+        Args:
+            data: Dictionary containing plant data from the API.
+        """
+        # The data attribute needs to be set manually because the API
+        # may return more results than the existing data attributes.
+        self.city = data.get("city", "")
+        self.country = data.get("country", "")
+        self.e_today = data.get("e_today", 0.0)
+        self.e_total = data.get("e_total", 0.0)
+        self.eid = data.get("eid", 0)
+        self.kwhimp = data.get("kwhimp", 0)
+        self.micro = data.get("micro", 0)
+        self.plant_id = data.get("plant_id", "")
+        self.plant_name = data.get("plant_name", "")
+        self.plant_type = data.get("plant_type", "")
+        self.power = data.get("power", 0)
+        self.status = data.get("status", "")

hyponcloud-0.1.0/hyponcloud.egg-info/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: hyponcloud
+Version: 0.1.0
+Summary: Python library for Hypontech Cloud API
+Author-email: jcisio <jcisio@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/jcisio/hyponcloud
+Project-URL: Repository, https://github.com/jcisio/hyponcloud
+Project-URL: Issues, https://github.com/jcisio/hyponcloud/issues
+Keywords: hypontech,solar,inverter,api,async
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Hypontech Cloud API Python Library
+
+A Python library for interacting with the Hypontech Cloud API for solar inverter monitoring.
+
+## Features
+
+- Async/await support using aiohttp
+- Get plant overview data (power, energy production, device status)
+- Get plant list
+- Automatic token management and refresh
+- Built-in retry logic for rate limiting
+- Type hints for better IDE support
+- Comprehensive error handling
+
+## Installation
+
+```bash
+pip install hyponcloud
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+import asyncio
+from hyponcloud import HyponCloud
+
+async def main():
+    # Create client with your credentials
+    async with HyponCloud("your_username", "your_password") as client:
+        # Connect and authenticate
+        if await client.connect():
+            # Get overview data
+            overview = await client.get_overview()
+            print(f"Current power: {overview.power}W")
+            print(f"Today's energy: {overview.e_today}kWh")
+            print(f"Total energy: {overview.e_total}kWh")
+
+            # Get plant list
+            plants = await client.get_list()
+            print(f"Number of plants: {len(plants)}")
+
+asyncio.run(main())
+```
+
+### Using with Custom aiohttp Session
+
+```python
+import aiohttp
+from hyponcloud import HyponCloud
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        client = HyponCloud("your_username", "your_password", session=session)
+
+        if await client.connect():
+            overview = await client.get_overview()
+            print(f"Power: {overview.power}W")
+
+asyncio.run(main())
+```
+
+### Error Handling
+
+```python
+from hyponcloud import (
+    HyponCloud,
+    AuthenticationError,
+    ConnectionError,
+    RateLimitError,
+)
+
+async def main():
+    try:
+        async with HyponCloud("username", "password") as client:
+            await client.connect()
+            overview = await client.get_overview()
+            print(f"Power: {overview.power}W")
+
+    except AuthenticationError as e:
+        print(f"Authentication failed: {e}")
+    except RateLimitError as e:
+        print(f"Rate limit exceeded: {e}")
+    except ConnectionError as e:
+        print(f"Connection error: {e}")
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### HyponCloud
+
+Main client class for interacting with the Hypontech Cloud API.
+
+#### Methods
+
+##### `__init__(username: str, password: str, session: aiohttp.ClientSession | None = None)`
+
+Initialize the client.
+
+- `username`: Your Hypontech Cloud username
+- `password`: Your Hypontech Cloud password
+- `session`: Optional aiohttp ClientSession. If not provided, one will be created automatically.
+
+##### `async connect() -> bool`
+
+Authenticate with the API and retrieve access token.
+
+**Returns:** `True` if successful, `False` otherwise
+
+**Raises:**
+- `AuthenticationError`: Invalid credentials
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async get_overview(retries: int = 3) -> OverviewData`
+
+Get plant overview data including power generation and device status.
+
+**Parameters:**
+- `retries`: Number of retry attempts on failure (default: 3)
+
+**Returns:** `OverviewData` object
+
+**Raises:**
+- `AuthenticationError`: Authentication required
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async get_list(retries: int = 3) -> list[dict]`
+
+Get list of plants associated with the account.
+
+**Parameters:**
+- `retries`: Number of retry attempts on failure (default: 3)
+
+**Returns:** List of plant dictionaries
+
+**Raises:**
+- `AuthenticationError`: Authentication required
+- `ConnectionError`: Network error
+- `RateLimitError`: Too many requests
+
+##### `async close() -> None`
+
+Close the aiohttp session (only if created by the library).
+
+### OverviewData
+
+Data class containing plant overview information.
+
+#### Attributes
+
+- `capacity` (float): Plant capacity
+- `capacity_company` (str): Capacity unit (e.g., "KW")
+- `power` (int): Current power generation in watts
+- `company` (str): Power unit (e.g., "W")
+- `percent` (int): Percentage value
+- `e_today` (float): Today's energy production in kWh
+- `e_total` (float): Total lifetime energy production in kWh
+- `fault_dev_num` (int): Number of faulty devices
+- `normal_dev_num` (int): Number of normal devices
+- `offline_dev_num` (int): Number of offline devices
+- `wait_dev_num` (int): Number of devices waiting
+- `total_co2` (int): Total CO2 savings
+- `total_tree` (float): Equivalent trees planted
+
+### PlantData
+
+Data class containing individual plant information.
+
+#### Attributes
+
+- `city` (str): Plant location city
+- `country` (str): Plant location country
+- `e_today` (float): Today's energy production
+- `e_total` (float): Total energy production
+- `eid` (int): Equipment ID
+- `kwhimp` (int): kWh import
+- `micro` (int): Micro inverter count
+- `plant_id` (str): Unique plant identifier
+- `plant_name` (str): Plant name
+- `plant_type` (str): Plant type
+- `power` (int): Current power
+- `status` (str): Plant status
+
+### Exceptions
+
+- `HyponCloudError`: Base exception for all library errors
+- `AuthenticationError`: Authentication failed (invalid credentials)
+- `ConnectionError`: Connection to API failed
+- `RateLimitError`: API rate limit exceeded
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/jcisio/hyponcloud.git
+cd hyponcloud
+
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+ruff check .
+ruff format .
+```
+
+### Type Checking
+
+```bash
+mypy hyponcloud
+```
+
+## Requirements
+
+- Python 3.11+
+- aiohttp 3.8.0+
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Disclaimer
+
+This library is not officially associated with or endorsed by Hypontech. Use at your own risk.
+
+## Support
+
+For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/jcisio/hyponcloud).

hyponcloud-0.1.0/hyponcloud.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+hyponcloud/__init__.py
+hyponcloud/client.py
+hyponcloud/exceptions.py
+hyponcloud/models.py
+hyponcloud/py.typed
+hyponcloud.egg-info/PKG-INFO
+hyponcloud.egg-info/SOURCES.txt
+hyponcloud.egg-info/dependency_links.txt
+hyponcloud.egg-info/requires.txt
+hyponcloud.egg-info/top_level.txt
+tests/test_client.py

hyponcloud-0.1.0/hyponcloud.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hyponcloud-0.1.0/hyponcloud.egg-info/requires.txt

@@ -0,0 +1,8 @@
+aiohttp>=3.8.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+pytest-cov>=4.0.0
+ruff>=0.1.0
+mypy>=1.0.0

hyponcloud-0.1.0/hyponcloud.egg-info/top_level.txt

@@ -0,0 +1 @@
+hyponcloud

hyponcloud-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyponcloud"
+version = "0.1.0"
+description = "Python library for Hypontech Cloud API"
+readme = "README.md"
+authors = [
+    {name = "jcisio", email = "jcisio@gmail.com"}
+]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+keywords = ["hypontech", "solar", "inverter", "api", "async"]
+requires-python = ">=3.11"
+dependencies = [
+    "aiohttp>=3.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jcisio/hyponcloud"
+Repository = "https://github.com/jcisio/hyponcloud"
+Issues = "https://github.com/jcisio/hyponcloud/issues"
+
+[tool.setuptools]
+packages = ["hyponcloud"]
+
+[tool.setuptools.package-data]
+hyponcloud = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

hyponcloud-0.1.0/setup.cfg

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

hyponcloud-0.1.0/tests/test_client.py

@@ -0,0 +1,29 @@
+"""Tests for HyponCloud client."""
+
+import pytest
+from aiohttp import ClientSession
+
+from hyponcloud import AuthenticationError, ConnectionError, HyponCloud
+
+
+@pytest.mark.asyncio
+async def test_client_initialization():
+    """Test client initialization."""
+    client = HyponCloud("test_user", "test_pass")
+    assert client.base_url == "https://api.hypon.cloud/v2"
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_client_with_session():
+    """Test client with custom session."""
+    async with ClientSession() as session:
+        client = HyponCloud("test_user", "test_pass", session=session)
+        assert client._session == session
+
+
+@pytest.mark.asyncio
+async def test_context_manager():
+    """Test client as context manager."""
+    async with HyponCloud("test_user", "test_pass") as client:
+        assert client._session is not None