pycityvisitorparking 0.2.0__py3-none-any.whl

pycityvisitorparking/__init__.py

@@ -0,0 +1,28 @@
+"""pyCityVisitorParking package."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import Client
+from .exceptions import AuthError, NetworkError, ProviderError, ValidationError
+from .models import Favorite, Permit, ProviderInfo, Reservation, ZoneValidityBlock
+
+try:
+    __version__ = version("pycityvisitorparking")
+except PackageNotFoundError:  # pragma: no cover - not installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AuthError",
+    "Client",
+    "Favorite",
+    "NetworkError",
+    "Permit",
+    "ProviderError",
+    "ProviderInfo",
+    "Reservation",
+    "ValidationError",
+    "ZoneValidityBlock",
+    "__version__",
+]

pycityvisitorparking/_version.py

@@ -0,0 +1,3 @@
+"""Package version for Hatch."""
+
+__version__ = "0.2.0"

pycityvisitorparking/client.py

@@ -0,0 +1,83 @@
+"""Client facade for provider discovery and instantiation."""
+
+from __future__ import annotations
+
+import importlib
+
+import aiohttp
+
+from .exceptions import ProviderError
+from .models import ProviderInfo
+from .provider.base import BaseProvider
+from .provider.loader import get_manifest, list_providers
+
+_DEFAULT_TIMEOUT = aiohttp.ClientTimeout(total=30)
+
+
+class Client:
+    """Facade for provider discovery and access."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession | None = None,
+        *,
+        base_url: str | None = None,
+        api_uri: str | None = None,
+        timeout: aiohttp.ClientTimeout | None = None,
+        retry_count: int = 0,
+    ) -> None:
+        self._session = session
+        self._owns_session = session is None
+        self._base_url = base_url
+        self._api_uri = api_uri
+        self._timeout = timeout or _DEFAULT_TIMEOUT
+        self._retry_count = max(0, retry_count)
+
+    async def __aenter__(self) -> Client:
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    async def list_providers(self) -> list[ProviderInfo]:
+        return list_providers()
+
+    async def get_provider(
+        self,
+        provider_id: str,
+        *,
+        base_url: str | None = None,
+        api_uri: str | None = None,
+    ) -> BaseProvider:
+        if not provider_id:
+            raise ProviderError("Provider id is required.")
+        manifest = get_manifest(provider_id)
+        module_name = f"pycityvisitorparking.provider.{provider_id}"
+        try:
+            module = importlib.import_module(module_name)
+        except ModuleNotFoundError as exc:
+            raise ProviderError("Provider module could not be imported.") from exc
+        provider_cls = getattr(module, "Provider", None)
+        if provider_cls is None:
+            raise ProviderError("Provider module does not export Provider.")
+        if not isinstance(provider_cls, type) or not issubclass(provider_cls, BaseProvider):
+            raise ProviderError("Provider must inherit from BaseProvider.")
+        session = self._ensure_session()
+        return provider_cls(
+            session,
+            manifest,
+            base_url=base_url if base_url is not None else self._base_url,
+            api_uri=api_uri if api_uri is not None else self._api_uri,
+            timeout=self._timeout,
+            retry_count=self._retry_count,
+        )
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession(timeout=self._timeout)
+        return self._session

pycityvisitorparking/exceptions.py

@@ -0,0 +1,21 @@
+"""Library exceptions."""
+
+
+class PyCityVisitorParkingError(Exception):
+    """Base exception for the library."""
+
+
+class AuthError(PyCityVisitorParkingError):
+    """Raised when authentication fails."""
+
+
+class NetworkError(PyCityVisitorParkingError):
+    """Raised when network communication fails."""
+
+
+class ValidationError(PyCityVisitorParkingError):
+    """Raised when inputs fail validation."""
+
+
+class ProviderError(PyCityVisitorParkingError):
+    """Raised when a provider returns an error or is misconfigured."""

pycityvisitorparking/models.py

@@ -0,0 +1,40 @@
+"""Public data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderInfo:
+    id: str
+    favorite_update_possible: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ZoneValidityBlock:
+    start_time: str
+    end_time: str
+
+
+@dataclass(frozen=True, slots=True)
+class Permit:
+    id: str
+    remaining_time: int
+    zone_validity: list[ZoneValidityBlock]
+
+
+@dataclass(frozen=True, slots=True)
+class Reservation:
+    id: str
+    name: str
+    license_plate: str
+    start_time: str
+    end_time: str
+
+
+@dataclass(frozen=True, slots=True)
+class Favorite:
+    id: str
+    name: str
+    license_plate: str

pycityvisitorparking/provider/AGENTS.md

@@ -0,0 +1,130 @@
+# AGENTS.md — Provider Authoring Guide (pyCityVisitorParking)
+
+✅ **Limit the PR to the provider folder only**
+- Add a provider by adding files only under:
+  `src/pycityvisitorparking/provider/<provider_id>/...`
+- ❌ Avoid modifying core code, models, loader, or shared tests for a provider PR.
+
+✅ **Use English as the primary project language**
+- Write all documentation, comments, docstrings, commit messages, and changelogs in English.
+- Use Dutch only when quoting provider UI text or official municipality wording, and label it clearly.
+
+✅ **Create the required provider structure**
+- Create `src/pycityvisitorparking/provider/<provider_id>/`.
+- Add these required files:
+  - `manifest.json`
+  - `__init__.py`
+  - `api.py`
+  - `const.py`
+  - `README.md`
+  - `CHANGELOG.md`
+- Add provider-specific tests and fixtures inside the provider folder when possible.
+
+✅ **Maintain provider documentation and changelog**
+- Write `README.md` inside the provider folder and include:
+  - provider description and official service name
+  - required login keys and example credential shapes
+  - supported operations and known limitations
+  - mapping notes for `zone_validity` and time handling
+  - links to official provider documentation where available
+- Write `CHANGELOG.md` inside the provider folder.
+- Keep an “Unreleased” section in the provider changelog.
+- Update provider `CHANGELOG.md` whenever endpoints, auth flow, mapping behavior, or limitations change.
+
+✅ **Verify documentation and pinned versions and correct assumptions**
+- Check the current project documentation and the versions pinned in our lockfiles and CI.
+- Update any assumptions immediately when documentation, lockfiles, and CI disagree.
+- Align any provider docs, examples, and test expectations with the pinned versions.
+- Avoid “latest” installs in CI and keep dev tooling versions pinned.
+
+✅ **Require docstrings and clear comments**
+- Add docstrings for all public modules, classes, and methods.
+- Add clear inline comments for non-obvious logic (e.g., time/UTC conversion, normalization, fallback behavior).
+- Keep comments/docstrings free of credentials, tokens, or other PII.
+
+✅ **Create a valid provider manifest**
+- Create `manifest.json` and include:
+  - `id` and match it exactly to the folder name
+  - `name`
+  - `favorite_update_possible`
+- Validate `manifest.json` against:
+  `src/pycityvisitorparking/provider/manifest.schema.json`
+- ❌ Avoid imports or side effects when defining the manifest.
+* Use integration-provided `base_url` and `api_uri` to build request URLs.
+* ❌ Do not embed municipality base URLs in provider code or manifests.
+
+✅ **Export the Provider class without side effects**
+- Export a class named `Provider` from `<provider_id>/__init__.py`.
+- Implement `pycityvisitorparking.provider.base.BaseProvider`.
+- ❌ Avoid network calls, file writes, or heavy work at import time.
+
+✅ **Map strictly to public dataclasses**
+- Map provider responses only into strict public dataclasses:
+  - `ProviderInfo`
+  - `Permit`
+  - `ZoneValidityBlock`
+  - `Reservation`
+  - `Favorite`
+- ❌ Avoid adding provider-specific fields to public models.
+
+✅ **Normalize license plates (mandatory)**
+- Normalize every plate to uppercase `A–Z0–9`.
+- Remove spaces and special characters.
+- Raise `ValidationError` for invalid or empty plates after normalization.
+
+✅ **Convert all timestamps to UTC**
+- Convert all provider timestamps to UTC before returning them.
+- Format all public timestamps as ISO 8601 with `Z` and without microseconds.
+- Ensure every returned timestamp is parseable as a timezone-aware UTC datetime.
+
+✅ **Filter zone_validity to chargeable windows**
+- Build `Permit.zone_validity` using only chargeable windows.
+- Filter out free windows.
+- Include windows only when reservation is required/chargeable.
+
+✅ **Implement login and auth safely**
+- Accept credentials via `Mapping[str, str]` or `**kwargs`.
+- Validate required keys and raise `ValidationError` when missing.
+- Raise `AuthError` for invalid credentials or expired sessions.
+- ❌ Avoid logging credentials or tokens.
+
+✅ **Use aiohttp and map errors safely**
+- Use the injected `aiohttp.ClientSession`.
+- Enforce timeouts and keep TLS verification enabled.
+- Translate errors into library exceptions.
+- ❌ Avoid leaking raw `aiohttp` exceptions.
+- Use relative paths and build requests from `base_url + api_uri`.
+
+✅ **Respect favorite update behavior**
+- Set `favorite_update_possible` to `true` only when native update is supported.
+- Set `favorite_update_possible` to `false` when native update is not supported.
+- Rely on core fallback behavior (remove+add) when update is not supported.
+
+✅ **Enforce reservation rules**
+- Require `end_time` for `start_reservation` and ❌ avoid defaults.
+- Enforce `end_time > start_time` and raise `ValidationError` when violated.
+
+✅ **Add tests without live calls**
+- ❌ Avoid live services.
+- Use fixtures and mocks.
+- Add tests that verify:
+  - license plate normalization
+  - UTC conversion from an offset timestamp
+  - `zone_validity` filtering to chargeable windows
+  - mapping into strict public dataclasses
+
+✅ **Make provider changes release-ready**
+- Update provider `CHANGELOG.md` when provider behavior changes.
+- Keep provider `README.md` accurate for required login keys and limitations.
+- ❌ Avoid adding new runtime dependencies without maintainer approval.
+
+✅ **Run the checklist before opening a PR**
+- Confirm adding files only under `provider/<provider_id>/`.
+- Confirm `manifest.json` validates against the schema.
+- Confirm `Provider` exports and ❌ avoid network calls on import.
+- Confirm UTC ISO 8601 `Z` timestamps in all public outputs.
+- Confirm license plate normalization and validation.
+- Confirm chargeable-only `zone_validity`.
+- Confirm `end_time` required and `end_time > start_time`.
+- Confirm provider `README.md` and `CHANGELOG.md` exist and are updated.
+- Confirm `pytest` passes.

pycityvisitorparking/provider/README.md

@@ -0,0 +1,173 @@
+# Provider Authoring Guide
+
+This document explains how to add a new provider to `pyCityVisitorParking`.
+Provider PRs must touch only `src/pycityvisitorparking/provider/<provider_id>/...`.
+
+## Required folder structure
+
+Create a new folder under `src/pycityvisitorparking/provider/`:
+
+```
+src/pycityvisitorparking/provider/<provider_id>/
+  manifest.json
+  __init__.py
+  api.py
+  const.py
+  README.md
+  CHANGELOG.md
+```
+
+The `<provider_id>` must be lowercase and match the `id` field in `manifest.json`.
+
+## Manifest requirements
+
+Each provider must include a `manifest.json` with:
+
+```json
+{
+  "id": "<provider_id>",
+  "name": "Display Name",
+  "favorite_update_possible": true
+}
+```
+
+Manifests are validated against:
+`src/pycityvisitorparking/provider/manifest.schema.json`.
+
+## Provider class export
+
+The provider package must export a class named `Provider` from
+`src/pycityvisitorparking/provider/<provider_id>/__init__.py`:
+
+```python
+from .api import Provider
+
+__all__ = ["Provider"]
+```
+
+The `Provider` class must inherit `pycityvisitorparking.provider.base.BaseProvider`
+and implement all required async methods.
+
+## Import safety
+
+Discovery reads manifests without importing provider code. Avoid side effects on
+import:
+
+- No network requests
+- No file writes
+- No heavy computation
+
+All setup should happen inside async methods.
+
+## Base URL and API URI
+
+Home Assistant supplies `base_url` and optionally `api_uri`. Provider code must
+use relative paths and join them with `base_url + api_uri` via
+`BaseProvider._build_url()` or `_request_json()` / `_request_text()`.
+
+Do not hardcode `base_url` or `api_uri` in provider code.
+
+## Authentication
+
+`login()` must accept `Mapping[str, str]` or `**kwargs`. Validate required keys
+and raise `ValidationError` for missing values. Raise `AuthError` for invalid
+credentials or expired sessions.
+
+Do not log credentials or tokens.
+
+## Time handling (UTC required)
+
+All public timestamps must be UTC ISO 8601 with a trailing `Z` and no
+microseconds. Convert provider-local or offset timestamps to UTC internally.
+
+Use utilities from `pycityvisitorparking.util`:
+
+- `ensure_utc_timestamp()`
+- `format_utc_timestamp()`
+- `parse_timestamp()`
+
+All timestamps must be timezone-aware and parseable.
+
+## License plate normalization
+
+Normalize plates to uppercase `A-Z0-9` and remove spaces/special characters.
+Raise `ValidationError` for invalid or empty plates after normalization.
+
+Use `normalize_license_plate()` from `pycityvisitorparking.util`.
+
+## Zone validity filtering
+
+`Permit.zone_validity` must include only chargeable windows.
+Filter out free or non-chargeable windows. Use
+`filter_chargeable_zone_validity()` from `pycityvisitorparking.util`.
+
+## Reservation validation
+
+`start_reservation()` requires both `start_time` and `end_time`.
+Enforce `end_time > start_time` and raise `ValidationError` when violated.
+
+Use `validate_reservation_times()` for shared validation and normalization.
+
+## Favorites update behavior
+
+Set `favorite_update_possible` in the manifest:
+
+- `true` only if the provider supports a native update endpoint.
+- `false` if updates require delete + add.
+
+When `favorite_update_possible` is `false`, the core fallback removes and re-adds
+the favorite. Providers should implement `_update_favorite_native()` even if the
+fallback is used (it can raise `ProviderError` if called unexpectedly).
+
+## Public models only
+
+Map all provider responses to strict public dataclasses in
+`pycityvisitorparking.models`:
+
+- `ProviderInfo`
+- `Permit`
+- `ZoneValidityBlock`
+- `Reservation`
+- `Favorite`
+
+Do not add provider-specific fields to public models.
+
+## HTTP safety
+
+Use the injected `aiohttp.ClientSession` from `BaseProvider`.
+Enable TLS verification and enforce timeouts.
+Translate network and HTTP errors into library exceptions.
+Never leak raw `aiohttp` exceptions.
+
+Retries are allowed only for idempotent GET requests and should be conservative
+or disabled.
+
+## Logging and PII
+
+Do not log credentials, tokens, or full license plates. If logging is necessary,
+mask plates using `mask_license_plate()`.
+
+## Documentation and changelog
+
+Each provider must include:
+
+- `README.md` with auth requirements, supported operations, limitations,
+  mapping notes, and links to official docs.
+- `CHANGELOG.md` with an `Unreleased` section. Update it when auth, endpoints,
+  mappings, or limitations change.
+
+## Tests
+
+Provider tests should use mocks/fixtures and avoid live services.
+Add coverage for:
+
+- license plate normalization
+- UTC conversion from provider timestamps
+- zone validity filtering
+- mapping into public models
+
+Run the test suite with:
+
+```bash
+hatch run test:run
+```

pycityvisitorparking/provider/__init__.py

@@ -0,0 +1 @@
+"""Provider package."""