Metadata-Version: 2.5
Name: aiobudgetthuis
Version: 0.1.1
Summary: Async Python client for the unofficial Budget Thuis (Budget Energie) API
Project-URL: Homepage, https://github.com/jdolieslager/aiobudgetthuis
Project-URL: Source, https://github.com/jdolieslager/aiobudgetthuis
Project-URL: Issues, https://github.com/jdolieslager/aiobudgetthuis/issues
Author: Jesper Dolieslager
License-Expression: MIT
License-File: LICENSE
Keywords: asyncio,budget-energie,budget-thuis,dynamic-prices,energy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.9
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.16.0; extra == 'dev'
Description-Content-Type: text/markdown

# aiobudgetthuis

[![CI](https://github.com/jdolieslager/aiobudgetthuis/actions/workflows/ci.yaml/badge.svg)](https://github.com/jdolieslager/aiobudgetthuis/actions/workflows/ci.yaml)
[![PyPI](https://img.shields.io/pypi/v/aiobudgetthuis)](https://pypi.org/project/aiobudgetthuis/)
[![Python](https://img.shields.io/pypi/pyversions/aiobudgetthuis)](https://pypi.org/project/aiobudgetthuis/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Async Python client for the **unofficial** Budget Thuis (Budget Energie) API: hourly dynamic
electricity prices, daily usage/solar production/cost, monthly installment, free-energy
windows, and contract discovery.

> **Unaffiliated.** This project is not affiliated with, endorsed by, or supported by
> Budget Thuis / Budget Energie. The API is not publicly documented and may change or
> break at any time. "Budget Thuis" is a trademark of its respective owner.

Built for the [ha-budget-thuis](https://github.com/jdolieslager/ha-budget-thuis) Home
Assistant integration, but usable standalone in any asyncio application.

## Install

```bash
pip install aiobudgetthuis
```

Requires Python 3.12+ and an `aiohttp` session managed by you.

## Usage

```python
import aiohttp

from aiobudgetthuis import BudgetThuisClient


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        client = BudgetThuisClient(session)

        # Login replays the server-rendered OAuth2 + PKCE form. Store only the
        # refresh token; never persist the password.
        tokens = await client.login("user@example.com", "password")

        contracts = await client.async_get_contracts(tokens.access_token)
        contract = next(c for c in contracts if c.is_active)

        from datetime import datetime, timedelta

        now = datetime.now().astimezone()
        details = await client.hourly_tariff(
            tokens.access_token, contract.id, now, now + timedelta(days=1)
        )
        for day in details.days:
            for tariff in day.electricity:
                print(tariff.period_from, tariff.total.gross)
```

Later sessions authenticate with `await client.refresh(refresh_token)`.

### API surface

- `login(username, password)` / `refresh(refresh_token)` → `Tokens`
- `async_get_contracts(access_token)` → `list[Contract]`
- `hourly_tariff(...)` → `HourlyTariffDetails` (wrap in `PriceData` for derived values:
  current/next slot, daily min/max/average, forecast attributes)
- `usage_summary(...)` → `UsageSummary` (per-day usage, solar production, cost, month-to-date)
- `monthly_amount(...)` → `MonthlyAmount` (installment)
- `free_energy_status(...)` → `FreeEnergyStatus`
- `contract_info(...)` → `ContractInfo`
- `daily_reading_mandate(...)` → `Mandate`

Errors: `BudgetThuisAuthError` (bad credentials / refused token) and
`BudgetThuisConnectionError` (network / unexpected upstream response), both subclasses of
`BudgetThuisError`.

## Related projects

- [`ha-budget-thuis`](https://github.com/jdolieslager/ha-budget-thuis) — Home Assistant (HACS) integration built on this client.

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check . && ruff format --check . && mypy src && pytest -q
```

## License

MIT
