Metadata-Version: 2.5
Name: aiolimburgnet
Version: 0.1.0
Summary: Async Python client for the public Limburg.net waste collection calendar API
Project-URL: Homepage, https://github.com/marcelhoffs/ha-limburg-net/tree/main/aiolimburgnet
Project-URL: Issues, https://github.com/marcelhoffs/ha-limburg-net/issues
Author: marcelhoffs
License-Expression: MIT
License-File: LICENSE
Keywords: belgium,home-assistant,limburg.net,recycling,waste
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Provides-Extra: test
Requires-Dist: aioresponses>=0.7; extra == 'test'
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# aiolimburgnet

Async Python client for the public [limburg.net](https://limburg.net) waste
collection calendar API. It has no dependency on Home Assistant — it's a
plain `aiohttp`-based library, usable standalone or as the backing library
for the `limburg_net` Home Assistant integration.

## Installation

```bash
pip install aiolimburgnet
```

## Usage

```python
import asyncio

import aiohttp

from aiolimburgnet import LimburgNetClient


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

        city = await client.find_city("Genk")
        street = await client.find_street(city, "Stationsstraat")

        events = await client.get_upcoming_events(
            city, street, house_number="12", suffix=""
        )

        for event in events:
            print(event.date, event.waste_type)


asyncio.run(main())
```

## API

- `LimburgNetClient(session: aiohttp.ClientSession)`
- `await client.find_city(query: str) -> City`
- `await client.find_street(city: City, query: str) -> Street`
- `await client.get_upcoming_events(city, street, house_number, suffix="", months_ahead=3) -> list[CollectionEvent]`

`City`, `Street`, and `CollectionEvent` are frozen dataclasses. All lookup
failures raise a subclass of `LimburgNetError`:

- `CityNotFoundError` — no city matched the search query
- `StreetNotFoundError` — no street matched the search query within that city
- `LimburgNetConnectionError` — the API could not be reached or returned an error

## Development

```bash
pip install -e ".[test]"
pytest
```
