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
• Get plant monitor data (real-time energy, power, earnings, environmental impact)
• Get inverter list for each plant
• Get administrator information
• Automatic token management and refresh
• Built-in retry logic for rate limiting
• Type hints for better IDE support
• Comprehensive error handling

Installation

pip install hyponcloud

Quick Start

Basic Usage

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
        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)}")

        # Get inverters for a specific plant
        if plants:
            inverters = await client.get_inverters(plants[0].plant_id)
            print(f"Number of inverters: {len(inverters)}")
            for inverter in inverters:
                print(f"  {inverter.model}: {inverter.power}W")

        # Get real-time monitor data for a specific plant
        if plants:
            monitor = await client.get_monitor(plants[0].plant_id)
            print(f"Today's energy: {monitor.e_today}kWh")
            print(f"Total earnings: {monitor.total_earning} {monitor.monetary}")

        # Get administrator information
        admin = await client.get_admin_info()
        print(f"Admin user: {admin.username}")
        print(f"Email: {admin.email}")

asyncio.run(main())

Using with Custom aiohttp Session

import aiohttp
from hyponcloud import HyponCloud

async def main():
    async with aiohttp.ClientSession() as session:
        client = HyponCloud("your_username", "your_password", session=session)

        await client.connect()
        overview = await client.get_overview()
        print(f"Power: {overview.power}W")

asyncio.run(main())

Configuring Retries

You can configure retry behavior globally at the client level, or override it per method call:

from hyponcloud import HyponCloud

async def main():
    # Set global retries to 5 for all API calls
    async with HyponCloud("username", "password", retries=5) as client:
        await client.connect()

        # Uses 5 retries (global setting)
        overview = await client.get_overview()

        # Override for specific call (uses 1 retry)
        plants = await client.get_list(retries=1)

        # Disable retries for this call
        admin = await client.get_admin_info(retries=0)

asyncio.run(main())

Error Handling

from hyponcloud import (
    HyponCloud,
    RequestError,
    AuthenticationError,
    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 RequestError as e:
        print(f"Connection error: {e}")

asyncio.run(main())

API Reference

See API.md for the full API reference.

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/jcisio/hyponcloud.git
cd hyponcloud

# Install development dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks (optional but recommended)
pre-commit install

Running Tests

pytest

Code Formatting

ruff check .
ruff format .

Type Checking

mypy hyponcloud

Version Management

This project uses setuptools-scm for automatic version management:

• Versions are automatically determined from git tags
• Use semantic versioning (e.g., v0.1.2)
• Create a git tag and push to trigger automated publishing via GitHub Actions

git tag v0.1.2
git push origin v0.1.2

Requirements

• Python 3.11+
• aiohttp 3.8.0+
• mashumaro 3.11+

Build Requirements

• setuptools-scm 8.0+ (automatically installed during build for version management)

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.