birtrashclient 0.1.0__tar.gz

birtrashclient-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install hatch
+      - run: hatch build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

birtrashclient-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Secrets / local config
+.env

birtrashclient-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: birtrashclient
+Version: 0.1.0
+Summary: Async client library for the BIR Trash Collection API
+Project-URL: Homepage, https://github.com/eirikgrindevoll/birtrashclient
+Project-URL: Bug Tracker, https://github.com/eirikgrindevoll/birtrashclient/issues
+License: MIT
+Classifier: Framework :: AsyncIO
+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: Topic :: Home Automation
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Description-Content-Type: text/markdown
+
+# birtrashclient
+
+Async Python client for the [BIR](https://bir.no) Trash Collection API.
+
+## Installation
+
+```bash
+pip install birtrashclient
+```
+
+## Usage
+
+```python
+import asyncio
+from birtrashclient import BirTrashClient
+
+async def main():
+    client = BirTrashClient(app_id="your_app_id", contractor_id="your_contractor_id")
+    await client.authenticate()
+
+    address_id = await client.search_address("Storgata 1, Bergen")
+    calendar = await client.get_calendar(address_id, "2024-01-01", "2024-12-31")
+
+    for entry in calendar:
+        print(entry)
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## API
+
+### `BirTrashClient(app_id, contractor_id, ...)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `app_id` | `str` | required | Application ID for API authentication |
+| `contractor_id` | `str` | required | Contractor ID for API authentication |
+| `request_timeout` | `int` | `10` | HTTP timeout in seconds |
+| `session` | `aiohttp.ClientSession` | `None` | Optional session to reuse |
+| `retries` | `int` | `3` | Retries on transient server errors |
+| `backoff_factor` | `float` | `2.0` | Exponential backoff base multiplier |
+
+### Methods
+
+- `authenticate()` — Fetch and store an auth token
+- `search_address(address)` — Resolve a street address to a property ID
+- `get_calendar(address_id, from_date, to_date)` — Get pickup schedule (dates as `YYYY-MM-DD`)
+- `close()` — Close the underlying HTTP session
+
+## Exceptions
+
+- `BirTrashAuthError` — Authentication failure
+- `BirTrashConnectionError` — Connection or HTTP error after retries
+
+## License
+
+MIT

birtrashclient-0.1.0/README.md

@@ -0,0 +1,59 @@
+# birtrashclient
+
+Async Python client for the [BIR](https://bir.no) Trash Collection API.
+
+## Installation
+
+```bash
+pip install birtrashclient
+```
+
+## Usage
+
+```python
+import asyncio
+from birtrashclient import BirTrashClient
+
+async def main():
+    client = BirTrashClient(app_id="your_app_id", contractor_id="your_contractor_id")
+    await client.authenticate()
+
+    address_id = await client.search_address("Storgata 1, Bergen")
+    calendar = await client.get_calendar(address_id, "2024-01-01", "2024-12-31")
+
+    for entry in calendar:
+        print(entry)
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## API
+
+### `BirTrashClient(app_id, contractor_id, ...)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `app_id` | `str` | required | Application ID for API authentication |
+| `contractor_id` | `str` | required | Contractor ID for API authentication |
+| `request_timeout` | `int` | `10` | HTTP timeout in seconds |
+| `session` | `aiohttp.ClientSession` | `None` | Optional session to reuse |
+| `retries` | `int` | `3` | Retries on transient server errors |
+| `backoff_factor` | `float` | `2.0` | Exponential backoff base multiplier |
+
+### Methods
+
+- `authenticate()` — Fetch and store an auth token
+- `search_address(address)` — Resolve a street address to a property ID
+- `get_calendar(address_id, from_date, to_date)` — Get pickup schedule (dates as `YYYY-MM-DD`)
+- `close()` — Close the underlying HTTP session
+
+## Exceptions
+
+- `BirTrashAuthError` — Authentication failure
+- `BirTrashConnectionError` — Connection or HTTP error after retries
+
+## License
+
+MIT

birtrashclient-0.1.0/birtrashclient/__init__.py

@@ -0,0 +1,9 @@
+"""BIR Trash Collection API client library."""
+
+from .client import BirTrashAuthError, BirTrashClient, BirTrashConnectionError
+
+__all__ = [
+    "BirTrashClient",
+    "BirTrashAuthError",
+    "BirTrashConnectionError",
+]

birtrashclient-0.1.0/birtrashclient/client.py

@@ -0,0 +1,247 @@
+"""Client library for the BIR Trash Collection API."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from typing import Any
+
+import aiohttp
+
+_LOGGER = logging.getLogger(__name__)
+
+TRANSIENT_STATUS_CODES = {500, 502, 503, 504}
+DEFAULT_RETRIES = 3
+DEFAULT_BACKOFF = 2.0
+
+
+class BirTrashAuthError(Exception):
+    """Exception raised when authentication fails."""
+
+
+class BirTrashConnectionError(Exception):
+    """Exception raised when a connection error occurs."""
+
+
+class BirTrashClient:
+    """Async client for the BIR Trash Collection API."""
+
+    def __init__(
+        self,
+        app_id: str,
+        contractor_id: str,
+        request_timeout: int = 10,
+        session: aiohttp.ClientSession | None = None,
+        retries: int = DEFAULT_RETRIES,
+        backoff_factor: float = DEFAULT_BACKOFF,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            app_id: The application ID for API authentication.
+            contractor_id: The contractor ID for API authentication.
+            request_timeout: Timeout in seconds for HTTP requests.
+            session: An optional aiohttp ClientSession to reuse.
+            retries: Number of retries for transient server errors.
+            backoff_factor: Base delay multiplier for exponential backoff.
+        """
+        self.base_url = "https://webservice.bir.no/api"
+        self.request_timeout = aiohttp.ClientTimeout(total=request_timeout)
+        self.app_id = app_id
+        self.contractor_id = contractor_id
+        self.token: str | None = None
+        self._session = session
+        self._close_session = False
+        self.retries = retries
+        self.backoff_factor = backoff_factor
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        """Return the active session, creating one if needed."""
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._close_session = True
+        return self._session
+
+    async def _request_with_retry(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute an HTTP request with retry logic for transient errors.
+
+        Args:
+            method: The HTTP method (get, post, etc.).
+            url: The full URL to request.
+            **kwargs: Additional arguments passed to the aiohttp request.
+
+        Returns:
+            The parsed JSON response.
+
+        Raises:
+            BirTrashAuthError: On 401 after re-authentication also fails.
+            BirTrashConnectionError: After all retries are exhausted.
+        """
+        session = await self._get_session()
+        last_exception: Exception | None = None
+
+        for attempt in range(self.retries + 1):
+            try:
+                async with session.request(
+                    method,
+                    url,
+                    timeout=self.request_timeout,
+                    **kwargs,
+                ) as response:
+                    if response.status == 401:
+                        _LOGGER.debug(
+                            "Token expired (attempt %d), re-authenticating",
+                            attempt + 1,
+                        )
+                        await self.authenticate()
+                        if "headers" in kwargs and kwargs["headers"]:
+                            kwargs["headers"]["Token"] = self.token
+                        continue
+
+                    if response.status in TRANSIENT_STATUS_CODES:
+                        delay = self.backoff_factor * (2 ** attempt)
+                        _LOGGER.warning(
+                            "Server returned %d (attempt %d/%d), "
+                            "retrying in %.1f s",
+                            response.status,
+                            attempt + 1,
+                            self.retries + 1,
+                            delay,
+                        )
+                        last_exception = BirTrashConnectionError(
+                            f"Server returned {response.status}"
+                        )
+                        await asyncio.sleep(delay)
+                        continue
+
+                    response.raise_for_status()
+                    return await response.json()
+
+            except (aiohttp.ClientError, asyncio.TimeoutError) as err:
+                delay = self.backoff_factor * (2 ** attempt)
+                _LOGGER.warning(
+                    "Request failed (attempt %d/%d): %s, retrying in %.1f s",
+                    attempt + 1,
+                    self.retries + 1,
+                    err,
+                    delay,
+                )
+                last_exception = err
+                if attempt < self.retries:
+                    await asyncio.sleep(delay)
+
+        raise BirTrashConnectionError(
+            f"Request failed after {self.retries + 1} attempts"
+        ) from last_exception
+
+    async def authenticate(self) -> None:
+        """Authenticate with the BIR API and store the token.
+
+        Raises:
+            BirTrashAuthError: If the authentication request fails.
+        """
+        session = await self._get_session()
+        try:
+            async with session.post(
+                f"{self.base_url}/login",
+                json={
+                    "applikasjonsId": self.app_id,
+                    "oppdragsgiverId": self.contractor_id,
+                },
+                timeout=self.request_timeout,
+            ) as response:
+                response.raise_for_status()
+                self.token = response.headers["Token"]
+        except (aiohttp.ClientError, asyncio.TimeoutError) as err:
+            raise BirTrashAuthError(
+                f"Authentication failed: {err}"
+            ) from err
+
+    @staticmethod
+    def _normalize_address(address: str) -> str:
+        """Insert a space between street number and unit letter if missing.
+
+        Converts e.g. '46J' -> '46 J' to match the API's expected format.
+        """
+        return re.sub(r"(\d)([A-Za-z])$", r"\1 \2", address.strip())
+
+    async def search_addresses(self, address: str) -> list[dict[str, Any]]:
+        """Search for an address and return all matching properties.
+
+        Useful for Home Assistant config flows where the user selects
+        from a list of matching properties (e.g. multiple units at one
+        street number).
+
+        Args:
+            address: The street address to search for.
+
+        Returns:
+            A list of property dicts, each containing at minimum 'id'
+            and 'adresse' keys.
+
+        Raises:
+            BirTrashConnectionError: If the request fails after retries.
+        """
+        return await self._request_with_retry(
+            "get",
+            f"{self.base_url}/eiendommer",
+            params={"adresse": self._normalize_address(address)},
+            headers={"Token": self.token},
+        )
+
+    async def search_address(self, address: str) -> str:
+        """Search for an address and return the corresponding property ID.
+
+        The address is normalized before searching — a space is inserted
+        between the street number and unit letter if missing
+        (e.g. '46J' becomes '46 J').
+
+        Args:
+            address: The street address to search for.
+
+        Returns:
+            The property ID string for the first matching property.
+
+        Raises:
+            BirTrashConnectionError: If the request fails after retries.
+        """
+        result = await self.search_addresses(address)
+        return result[0].get("id")
+
+    async def get_calendar(
+        self, address_id: str, from_date: str, to_date: str
+    ) -> list[dict[str, Any]]:
+        """Get the pickup calendar for the provided address ID.
+
+        Args:
+            address_id: The property ID to query.
+            from_date: The start date in YYYY-MM-DD format.
+            to_date: The end date in YYYY-MM-DD format.
+
+        Returns:
+            A list of pickup schedule dictionaries.
+
+        Raises:
+            BirTrashConnectionError: If the request fails after retries.
+        """
+        return await self._request_with_retry(
+            "get",
+            f"{self.base_url}/tomminger",
+            params={
+                "datoFra": from_date,
+                "datoTil": to_date,
+                "eiendomId": address_id,
+            },
+            headers={"Token": self.token},
+        )
+
+    async def close(self) -> None:
+        """Close the underlying session if we own it."""
+        if self._session and self._close_session:
+            await self._session.close()

birtrashclient-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "birtrashclient"
+version = "0.1.0"
+description = "Async client library for the BIR Trash Collection API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "aiohttp>=3.9",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Framework :: AsyncIO",
+    "Topic :: Home Automation",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/eirikgrindevoll/birtrashclient"
+"Bug Tracker" = "https://github.com/eirikgrindevoll/birtrashclient/issues"

birtrashclient-0.1.0/test_integration.py

@@ -0,0 +1,53 @@
+"""Integration test against the real BIR API.
+
+Usage:
+    BIR_APP_ID=xxx BIR_CONTRACTOR_ID=yyy BIR_ADDRESS="Storgata 1" python test_integration.py
+"""
+
+import asyncio
+import os
+from datetime import date, timedelta
+
+from birtrashclient import BirTrashAuthError, BirTrashClient, BirTrashConnectionError
+
+
+async def main() -> None:
+    app_id = os.environ.get("BIR_APP_ID")
+    contractor_id = os.environ.get("BIR_CONTRACTOR_ID")
+    address = os.environ.get("BIR_ADDRESS")
+
+    if not app_id or not contractor_id or not address:
+        raise SystemExit(
+            "Set BIR_APP_ID, BIR_CONTRACTOR_ID, and BIR_ADDRESS environment variables."
+        )
+
+    client = BirTrashClient(app_id=app_id, contractor_id=contractor_id)
+
+    try:
+        print("Authenticating...")
+        await client.authenticate()
+        print(f"  Token: {client.token[:20]}...")
+
+        print(f"\nSearching for address: {address!r}")
+        address_id = await client.search_address(address)
+        print(f"  Property ID: {address_id}")
+
+        from_date = date.today().isoformat()
+        to_date = (date.today() + timedelta(days=90)).isoformat()
+        print(f"\nFetching calendar ({from_date} -> {to_date})...")
+        calendar = await client.get_calendar(address_id, from_date, to_date)
+        print(f"  {len(calendar)} pickup(s) found:")
+        for entry in calendar:
+            print(f"    {entry}")
+
+    except BirTrashAuthError as err:
+        print(f"Auth error: {err}")
+        raise SystemExit(1)
+    except BirTrashConnectionError as err:
+        print(f"Connection error: {err}")
+        raise SystemExit(1)
+    finally:
+        await client.close()
+
+
+asyncio.run(main())