Metadata-Version: 2.4
Name: stromnetz-berlin-lastgang
Version: 0.1.1
Summary: Async client for Stromnetz Berlin Lastgang consumption data
Author: stromnetz-berlin-lastgang contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/ress/stromnetz-berlin-lastgang
Project-URL: Issues, https://github.com/ress/stromnetz-berlin-lastgang/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
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
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4.0.0,>=3.11.0
Provides-Extra: test
Requires-Dist: pytest>=8.3.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "test"
Requires-Dist: pytest-cov>=6.0.0; extra == "test"
Requires-Dist: ruff>=0.12.0; extra == "test"
Dynamic: license-file

# stromnetz-berlin-lastgang

An unofficial asynchronous Python client for historical electricity-consumption
data from
[`lastgang-online.stromnetz.berlin`](https://lastgang-online.stromnetz.berlin/).

> [!IMPORTANT]
> This project is an early alpha and uses an undocumented web-portal protocol.
> It is not affiliated with or supported by Stromnetz Berlin. Portal changes can
> break it without notice.

## Features

- Async authentication with automatic retry after portal session expiry.
- Discovery of consumption locations, Zählpunkte, and time series.
- Quarter-hour CSV exports explicitly requested and validated as kWh.
- DST-safe timestamps, including both repeated autumn hours.
- Missing provider intervals preserved as gaps.
- Exact UTC-hour aggregation for statistics-oriented consumers.
- Serialized 31-day exports with configurable request pacing.

The client deliberately uses the portal's CSV export. The chart endpoint rounds
values and collapses the repeated hour at the end of daylight-saving time; CSV
retains the original precision and all 100 quarter-hours. The client preserves
quarter-hour readings and resolves DST by validated row order.

`aggregate_hourly()` aggregates exactly four consecutive UTC quarters and
marks affected hours incomplete when provider intervals are absent.

## Installation

```bash
python -m pip install stromnetz-berlin-lastgang
```

## Example

```python
from datetime import date

from aiohttp import ClientSession, CookieJar

from stromnetz_berlin_lastgang import Selection, StromnetzBerlinClient


async def read_day(username: str, password: str):
    async with ClientSession(cookie_jar=CookieJar(quote_cookie=False)) as session:
        client = StromnetzBerlinClient(session, username, password)
        location = (await client.get_consumption_locations())[0]
        point = (await client.get_metering_points(location))[0]
        series = point.time_series[0]
        selection = Selection(location, point, series)
        return await client.get_readings(
            selection,
            date(2026, 1, 1),
            date(2026, 1, 1),
        )
```

`Reading.timestamp` is the timezone-aware UTC interval end and `Reading.value`
is a `Decimal` in kWh. Applications should let users choose a location,
Zählpunkt, and compatible consumption series instead of silently selecting the
first catalog entries as the short example does.

## Development

Python 3.12 or newer is required.

```bash
python3 -m venv .venv
.venv/bin/python -m pip install --editable '.[test]'
.venv/bin/python -m pytest
.venv/bin/python -m ruff check src tests tools
```

Never add portal credentials, cookies, CSRF tokens, addresses, Zählpunkte, or
raw consumption exports to fixtures, logs, or commits.

## Home Assistant

The companion Home Assistant integration is maintained separately at
[`ress/home-assistant-stromnetz-berlin-lastgang`](https://github.com/ress/home-assistant-stromnetz-berlin-lastgang).

## Security and privacy

The client accepts credentials only at runtime and never intentionally logs
them. Applications remain responsible for protecting credential storage and
consumption data.

See [the architecture notes](docs/architecture.md) for the protocol and data
model.

Released under the [MIT License](LICENSE).

