EPA-PM-API-Wrapper 0.3.0__py3-none-any.whl

epa_pm_api_wrapper/client.py

@@ -0,0 +1,507 @@
+"""EPA Portfolio Manager API client.
+
+Two clients are exposed:
+
+- :class:`EpaPmClient` (sync, ``httpx.Client`` backend)
+- :class:`EpaPmAsyncClient` (async, ``httpx.AsyncClient`` backend)
+
+Both expose the API as attribute-namespaced resources::
+
+    client.account.get()
+    client.property.list(account_id)
+    client.report.templates.list()
+
+…with the difference that async resource methods are coroutines::
+
+    async with EpaPmAsyncClient(user, pwd) as c:
+        acc = await c.account.get()
+
+This module holds the shared HTTP plumbing (auth, base URL, request body
+construction, error mapping, response parsing). The concrete request
+methods live on each client (sync ``_request``, async ``_arequest``).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, TypeVar, cast, overload
+
+import httpx
+from xsdata.formats.dataclass.parsers import XmlParser
+from xsdata.formats.dataclass.serializers import XmlSerializer
+from xsdata.formats.dataclass.serializers.config import SerializerConfig
+
+from epa_pm_api_wrapper.exceptions import EpaErrorDetail, EpaPmApiError, EpaPmAuthError
+from epa_pm_api_wrapper.models import Response
+from epa_pm_api_wrapper.resources import (
+    AccountResource,
+    AssociationResource,
+    AsyncAccountResource,
+    AsyncAssociationResource,
+    AsyncBuildingResource,
+    AsyncConsumptionDataResource,
+    AsyncCustomerResource,
+    AsyncCustomMetricResource,
+    AsyncDataExchangeResource,
+    AsyncGreenPowerResource,
+    AsyncHeyResource,
+    AsyncHierarchyResource,
+    AsyncIdentifierResource,
+    AsyncMeterResource,
+    AsyncMetricsResource,
+    AsyncPropertyResource,
+    AsyncPropertyUseResource,
+    AsyncReportResource,
+    AsyncShareResource,
+    AsyncTargetFinderResource,
+    AsyncVerificationResource,
+    AsyncWasteDataResource,
+    BuildingResource,
+    ConsumptionDataResource,
+    CustomerResource,
+    CustomMetricResource,
+    DataExchangeResource,
+    GreenPowerResource,
+    HeyResource,
+    HierarchyResource,
+    IdentifierResource,
+    MeterResource,
+    MetricsResource,
+    PropertyResource,
+    PropertyUseResource,
+    ReportResource,
+    ShareResource,
+    TargetFinderResource,
+    VerificationResource,
+    WasteDataResource,
+)
+from epa_pm_api_wrapper.retry import AsyncRetryTransport, RetryConfig, RetryTransport
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def _resolve_retry(retries: int | None, retry: RetryConfig | None) -> RetryConfig | None:
+    """Resolve the retry config from the two convenience kwargs.
+
+    ``retry`` wins if explicitly provided. ``retries`` overrides only the
+    attempt count. ``retries=0`` disables retries (returns ``None``).
+    Default is ``RetryConfig()`` (3 retries, exponential backoff).
+    """
+    if retry is not None:
+        return retry
+    if retries == 0:
+        return None
+    if retries is not None:
+        return RetryConfig(max_retries=retries)
+    return RetryConfig()
+
+
+def _wrap_transport_sync(
+    transport: httpx.BaseTransport | None,
+    retries: int | None,
+    retry: RetryConfig | None,
+) -> httpx.BaseTransport | None:
+    cfg = _resolve_retry(retries, retry)
+    if cfg is None:
+        return transport
+    return RetryTransport(transport, config=cfg)
+
+
+def _wrap_transport_async(
+    transport: httpx.AsyncBaseTransport | None,
+    retries: int | None,
+    retry: RetryConfig | None,
+) -> httpx.AsyncBaseTransport | None:
+    cfg = _resolve_retry(retries, retry)
+    if cfg is None:
+        return transport
+    return AsyncRetryTransport(transport, config=cfg)
+
+
+def _to_int(value: str | None) -> int | None:
+    """Parse an error number string into an int; return ``None`` on failure.
+
+    The XSD declares ``errorNumber`` as a string, but in practice the EPA
+    sends integer values (including negative ones like ``-200``). Callers
+    branch on integers, so we coerce here and fall back to ``None`` if a
+    future response ever surprises us with a non-integer code.
+    """
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+class _BaseClient:
+    """Plumbing shared by sync and async clients (no I/O methods)."""
+
+    LIVE_BASE_URL = "https://portfoliomanager.energystar.gov/ws"
+    TEST_BASE_URL = "https://portfoliomanager.energystar.gov/wstest"
+    DEFAULT_TIMEOUT = 30.0
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        base_url: str | None = None,
+        use_test_env: bool = False,
+    ):
+        if base_url:
+            self.base_url = base_url.rstrip("/")
+        elif use_test_env:
+            self.base_url = self.TEST_BASE_URL
+        else:
+            self.base_url = self.LIVE_BASE_URL
+
+        self.auth = (username, password)
+        self.parser = XmlParser()
+        self.serializer = XmlSerializer(config=SerializerConfig(indent="  "))
+
+    def _build_request(
+        self,
+        path: str,
+        data: Any = None,
+        params: dict | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> tuple[str, bytes | str | None, dict | None, dict[str, str]]:
+        """Return ``(url, content, params, headers)`` ready for ``httpx.request``.
+
+        Centralizes URL construction, XML body rendering (when ``data`` is a
+        dataclass), Content-Type header injection, and the drop-None pass on
+        query params (so resources can forward optional kwargs directly).
+        """
+        url = f"{self.base_url}/{path.lstrip('/')}"
+
+        content: bytes | str | None = None
+        headers: dict[str, str] = {}
+        if data is not None:
+            content = self.serializer.render(data)
+            headers["Content-Type"] = "application/xml"
+        if extra_headers:
+            headers.update(extra_headers)
+
+        if params is not None:
+            params = {k: v for k, v in params.items() if v is not None}
+            if not params:
+                params = None
+
+        return url, content, params, headers
+
+    def _raise_for_response(self, resp: httpx.Response) -> None:
+        """Raise the right exception type for a non-2xx response.
+
+        401 → :class:`EpaPmAuthError`. Other non-2xx → :class:`EpaPmApiError`,
+        carrying ``errors`` parsed from a ``<response status="Error">`` body
+        when present so callers can branch on EPA error numbers without
+        regex'ing the message string.
+        """
+        if resp.status_code == 401:
+            raise EpaPmAuthError(resp.status_code, resp.text)
+
+        if 200 <= resp.status_code < 300:
+            return
+
+        errors: list[EpaErrorDetail] = []
+        message = resp.text
+        try:
+            parsed = self.parser.from_string(resp.text, Response)
+            if parsed and parsed.errors and parsed.errors.error:
+                errors = [
+                    EpaErrorDetail(
+                        error_number=_to_int(e.error_number),
+                        error_description=e.error_description,
+                    )
+                    for e in parsed.errors.error
+                ]
+                message = "; ".join(f"{e.error_number}: {e.error_description}" for e in parsed.errors.error)
+        except Exception as exc:
+            # Body wasn't a parseable error envelope; fall through with raw text.
+            logger.debug("could not parse error envelope (status=%d): %s", resp.status_code, exc)
+
+        logger.warning(
+            "EPA PM %s %s -> %d: %s",
+            resp.request.method,
+            resp.request.url,
+            resp.status_code,
+            message,
+        )
+        raise EpaPmApiError(resp.status_code, message, errors=errors)
+
+    def _parse_typed(self, resp: httpx.Response, response_type: type[T]) -> T:
+        """Parse a 2xx body to the given dataclass type or raise on failure."""
+        if not resp.text:
+            raise EpaPmApiError(resp.status_code, "Expected response body but got empty response")
+        result = self.parser.from_string(resp.text, response_type)
+        if result is None:
+            raise EpaPmApiError(resp.status_code, "Failed to parse response")
+        return cast(T, result)
+
+    def _parse_polymorphic(self, resp: httpx.Response) -> Any:
+        """Parse a 2xx body to whichever dataclass matches the root element."""
+        if not resp.text:
+            raise EpaPmApiError(resp.status_code, "Expected response body but got empty response")
+        result = self.parser.from_string(resp.text)
+        if result is None:
+            raise EpaPmApiError(resp.status_code, "Failed to parse response")
+        return result
+
+
+class EpaPmClient(_BaseClient):
+    """Sync client.
+
+    Use as a context manager (``with EpaPmClient(...) as c:``) to release
+    the connection pool on exit, or call :meth:`close` manually.
+    """
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        base_url: str | None = None,
+        use_test_env: bool = False,
+        timeout: float | httpx.Timeout | None = None,
+        transport: httpx.BaseTransport | None = None,
+        http_client: httpx.Client | None = None,
+        retries: int | None = None,
+        retry: RetryConfig | None = None,
+    ):
+        """Construct a sync client.
+
+        Pass ``http_client`` to fully control the underlying ``httpx.Client``
+        (proxies, custom transports, mounts, event hooks); when supplied,
+        ``timeout``, ``transport``, ``retries``, and ``retry`` are ignored.
+        Otherwise the client builds its own ``httpx.Client`` with basic auth,
+        follow_redirects, the given timeout (default ``DEFAULT_TIMEOUT``
+        seconds), and an optional ``transport`` automatically wrapped with
+        :class:`RetryTransport`.
+
+        Retry behavior defaults to ``RetryConfig()`` (3 retries on 429/5xx
+        with exponential backoff). Pass ``retries=0`` to disable, ``retries=N``
+        to override just the attempt count, or ``retry=RetryConfig(...)`` for
+        full control.
+        """
+        super().__init__(username, password, base_url=base_url, use_test_env=use_test_env)
+
+        if http_client is not None:
+            self.client = http_client
+            self._owns_client = False
+        else:
+            transport = _wrap_transport_sync(transport, retries, retry)
+            self.client = httpx.Client(
+                auth=self.auth,
+                timeout=self.DEFAULT_TIMEOUT if timeout is None else timeout,
+                transport=transport,
+                follow_redirects=True,
+            )
+            self._owns_client = True
+
+        self.account = AccountResource(self)
+        self.association = AssociationResource(self)
+        self.building = BuildingResource(self)
+        self.consumption_data = ConsumptionDataResource(self)
+        self.custom_metric = CustomMetricResource(self)
+        self.customer = CustomerResource(self)
+        self.data_exchange = DataExchangeResource(self)
+        self.green_power = GreenPowerResource(self)
+        self.hey = HeyResource(self)
+        self.hierarchy = HierarchyResource(self)
+        self.identifier = IdentifierResource(self)
+        self.meter = MeterResource(self)
+        self.metrics = MetricsResource(self)
+        self.property = PropertyResource(self)
+        self.property_use = PropertyUseResource(self)
+        self.report = ReportResource(self)
+        self.share = ShareResource(self)
+        self.target_finder = TargetFinderResource(self)
+        self.verification = VerificationResource(self)
+        self.waste_data = WasteDataResource(self)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release its connection pool.
+
+        Only closes a client that this instance constructed. If a custom
+        ``http_client`` was passed in at init, ownership stays with the
+        caller and ``close`` is a no-op.
+        """
+        if self._owns_client:
+            self.client.close()
+
+    def __enter__(self) -> EpaPmClient:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.close()
+
+    @overload
+    def _request(
+        self,
+        method: str,
+        path: str,
+        data: Any = None,
+        params: dict | None = None,
+        response_type: type[T] = ...,
+        extra_headers: dict[str, str] | None = None,
+    ) -> T: ...
+
+    @overload
+    def _request(
+        self,
+        method: str,
+        path: str,
+        data: Any = None,
+        params: dict | None = None,
+        response_type: None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None: ...
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        data: Any = None,
+        params: dict | None = None,
+        response_type: type[T] | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> T | None:
+        url, content, params, headers = self._build_request(path, data, params, extra_headers)
+        logger.debug("EPA PM %s %s params=%s", method, url, params)
+        resp = self.client.request(method, url, content=content, params=params, headers=headers)
+        self._raise_for_response(resp)
+        if response_type:
+            return self._parse_typed(resp, response_type)
+        return None
+
+    def _request_polymorphic(self, method: str, path: str) -> Any:
+        """GET-style request that auto-resolves the response to its concrete subtype.
+
+        Use this for endpoints whose response element name is not fixed —
+        e.g. ``GET /propertyUse/{id}`` returns ``<office>``, ``<hotel>``,
+        ``<vehicleDealership>``, etc. depending on the use type. xsdata's
+        ``XmlContext`` resolves the root element to the matching dataclass
+        when ``from_string`` is called without an explicit type.
+        """
+        url, _, _, _ = self._build_request(path)
+        logger.debug("EPA PM %s %s (polymorphic)", method, url)
+        resp = self.client.request(method, url)
+        self._raise_for_response(resp)
+        return self._parse_polymorphic(resp)
+
+
+class EpaPmAsyncClient(_BaseClient):
+    """Async client backed by ``httpx.AsyncClient``.
+
+    Use as an async context manager (``async with EpaPmAsyncClient(...) as c:``)
+    to release the connection pool on exit, or call :meth:`aclose` manually.
+    All resource methods are coroutines and must be ``await``-ed.
+    """
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        base_url: str | None = None,
+        use_test_env: bool = False,
+        timeout: float | httpx.Timeout | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        retries: int | None = None,
+        retry: RetryConfig | None = None,
+    ):
+        """Construct an async client. See :class:`EpaPmClient` for parameter docs."""
+        super().__init__(username, password, base_url=base_url, use_test_env=use_test_env)
+
+        if http_client is not None:
+            self.client = http_client
+            self._owns_client = False
+        else:
+            transport = _wrap_transport_async(transport, retries, retry)
+            self.client = httpx.AsyncClient(
+                auth=self.auth,
+                timeout=self.DEFAULT_TIMEOUT if timeout is None else timeout,
+                transport=transport,
+                follow_redirects=True,
+            )
+            self._owns_client = True
+
+        self.account = AsyncAccountResource(self)
+        self.association = AsyncAssociationResource(self)
+        self.building = AsyncBuildingResource(self)
+        self.consumption_data = AsyncConsumptionDataResource(self)
+        self.custom_metric = AsyncCustomMetricResource(self)
+        self.customer = AsyncCustomerResource(self)
+        self.data_exchange = AsyncDataExchangeResource(self)
+        self.green_power = AsyncGreenPowerResource(self)
+        self.hey = AsyncHeyResource(self)
+        self.hierarchy = AsyncHierarchyResource(self)
+        self.identifier = AsyncIdentifierResource(self)
+        self.meter = AsyncMeterResource(self)
+        self.metrics = AsyncMetricsResource(self)
+        self.property = AsyncPropertyResource(self)
+        self.property_use = AsyncPropertyUseResource(self)
+        self.report = AsyncReportResource(self)
+        self.share = AsyncShareResource(self)
+        self.target_finder = AsyncTargetFinderResource(self)
+        self.verification = AsyncVerificationResource(self)
+        self.waste_data = AsyncWasteDataResource(self)
+
+    async def aclose(self) -> None:
+        """Close the underlying ``httpx.AsyncClient`` (skipped if injected)."""
+        if self._owns_client:
+            await self.client.aclose()
+
+    async def __aenter__(self) -> EpaPmAsyncClient:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, tb: object) -> None:
+        await self.aclose()
+
+    @overload
+    async def _arequest(
+        self,
+        method: str,
+        path: str,
+        data: Any = None,
+        params: dict | None = None,
+        response_type: type[T] = ...,
+        extra_headers: dict[str, str] | None = None,
+    ) -> T: ...
+
+    @overload
+    async def _arequest(
+        self,
+        method: str,
+        path: str,
+        data: Any = None,
+        params: dict | None = None,
+        response_type: None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None: ...
+
+    async def _arequest(
+        self,
+        method: str,
+        path: str,
+        data: Any = None,
+        params: dict | None = None,
+        response_type: type[T] | None = None,
+        extra_headers: dict[str, str] | None = None,
+    ) -> T | None:
+        url, content, params, headers = self._build_request(path, data, params, extra_headers)
+        logger.debug("EPA PM %s %s params=%s", method, url, params)
+        resp = await self.client.request(method, url, content=content, params=params, headers=headers)
+        self._raise_for_response(resp)
+        if response_type:
+            return self._parse_typed(resp, response_type)
+        return None
+
+    async def _arequest_polymorphic(self, method: str, path: str) -> Any:
+        """Async equivalent of :meth:`EpaPmClient._request_polymorphic`."""
+        url, _, _, _ = self._build_request(path)
+        logger.debug("EPA PM %s %s (polymorphic)", method, url)
+        resp = await self.client.request(method, url)
+        self._raise_for_response(resp)
+        return self._parse_polymorphic(resp)

epa_pm_api_wrapper/exceptions.py

@@ -0,0 +1,67 @@
+"""Exception types raised by the client.
+
+``EpaPmApiError`` carries the raw HTTP details *and* the structured EPA
+error payload when the body parses as ``<response status="Error">``. The
+flattened message string is preserved for backwards compatibility, but
+production callers should prefer ``error_number`` / ``errors`` for
+branching.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EpaErrorDetail:
+    """One ``<error>`` element from an EPA error response."""
+
+    error_number: int | None
+    error_description: str | None
+
+
+class EpaPmError(Exception):
+    """Base exception for EPA PM API Wrapper."""
+
+
+class EpaPmApiError(EpaPmError):
+    """Exception raised for errors returned by the API.
+
+    :ivar status_code: HTTP status code.
+    :ivar response_text: Raw response body (XML or plain text).
+    :ivar errors: Parsed list of EPA ``<error>`` entries when the body was
+        a structured ``<response status="Error">`` payload; empty otherwise.
+    :ivar error_number: Convenience accessor for the *first* EPA error
+        number when there's exactly one error in the payload — handy for
+        ``except EpaPmApiError as e: if e.error_number == 10: ...``. Use
+        :attr:`errors` if multiple errors may be present.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        response_text: str,
+        errors: list[EpaErrorDetail] | None = None,
+    ):
+        self.status_code = status_code
+        self.response_text = response_text
+        self.errors: list[EpaErrorDetail] = errors or []
+        super().__init__(f"API error {status_code}: {response_text}")
+
+    @property
+    def error_number(self) -> int | None:
+        """The EPA error number when exactly one error was reported, else ``None``."""
+        if len(self.errors) == 1:
+            return self.errors[0].error_number
+        return None
+
+
+class EpaPmAuthError(EpaPmApiError):
+    """Exception raised for authentication errors."""
+
+    def __init__(self, status_code: int, response_text: str):
+        super().__init__(status_code, response_text)
+        self.args = (
+            "Authentication failed. Please check your credentials (username/password) and ensure "
+            f"you are targeting the correct environment (live vs test). Details: {response_text}",
+        )