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

epa_pm_api_wrapper/resources/hierarchy.py

@@ -0,0 +1,59 @@
+"""ID hierarchy resource — `/idHierarchy/{resource}/{id}` endpoints."""
+
+from __future__ import annotations
+
+from epa_pm_api_wrapper.models import Hierarchy
+
+from ._base import AsyncResource, Resource
+
+
+class HierarchyResource(Resource):
+    def property(self, property_id: int) -> Hierarchy:
+        """Get account/property identifiers for a property."""
+        return self._client._request("GET", f"idHierarchy/property/{property_id}", response_type=Hierarchy)
+
+    def meter(self, meter_id: int) -> Hierarchy:
+        """Get account/property/meter identifiers for a meter."""
+        return self._client._request("GET", f"idHierarchy/meter/{meter_id}", response_type=Hierarchy)
+
+    def property_use(self, property_use_id: int) -> Hierarchy:
+        """Get account/property/propertyUse identifiers for a property use."""
+        return self._client._request("GET", f"idHierarchy/propertyUse/{property_use_id}", response_type=Hierarchy)
+
+    def consumption_data(self, consumption_data_id: int) -> Hierarchy:
+        """Get account/property/meter identifiers for a consumption data record."""
+        return self._client._request(
+            "GET", f"idHierarchy/consumptionData/{consumption_data_id}", response_type=Hierarchy
+        )
+
+    def use_details(self, use_details_id: int) -> Hierarchy:
+        """Get account/property/propertyUse identifiers for a use-details record."""
+        return self._client._request("GET", f"idHierarchy/useDetails/{use_details_id}", response_type=Hierarchy)
+
+    def waste_data(self, waste_data_id: int) -> Hierarchy:
+        """Get account/property/meter identifiers for a waste-data record."""
+        return self._client._request("GET", f"idHierarchy/wasteData/{waste_data_id}", response_type=Hierarchy)
+
+
+class AsyncHierarchyResource(AsyncResource):
+    async def property(self, property_id: int) -> Hierarchy:
+        return await self._client._arequest("GET", f"idHierarchy/property/{property_id}", response_type=Hierarchy)
+
+    async def meter(self, meter_id: int) -> Hierarchy:
+        return await self._client._arequest("GET", f"idHierarchy/meter/{meter_id}", response_type=Hierarchy)
+
+    async def property_use(self, property_use_id: int) -> Hierarchy:
+        return await self._client._arequest(
+            "GET", f"idHierarchy/propertyUse/{property_use_id}", response_type=Hierarchy
+        )
+
+    async def consumption_data(self, consumption_data_id: int) -> Hierarchy:
+        return await self._client._arequest(
+            "GET", f"idHierarchy/consumptionData/{consumption_data_id}", response_type=Hierarchy
+        )
+
+    async def use_details(self, use_details_id: int) -> Hierarchy:
+        return await self._client._arequest("GET", f"idHierarchy/useDetails/{use_details_id}", response_type=Hierarchy)
+
+    async def waste_data(self, waste_data_id: int) -> Hierarchy:
+        return await self._client._arequest("GET", f"idHierarchy/wasteData/{waste_data_id}", response_type=Hierarchy)

epa_pm_api_wrapper/resources/identifier.py

@@ -0,0 +1,92 @@
+"""Property additional identifier resource — `/property/{propertyId}/identifier`
+endpoints plus the catalog at `/property/identifier/list`.
+"""
+
+from __future__ import annotations
+
+from epa_pm_api_wrapper.models import (
+    AdditionalIdentifier,
+    AdditionalIdentifiers,
+    AdditionalIdentifierTypes,
+    Response,
+)
+
+from ._base import AsyncResource, Resource
+
+
+class IdentifierResource(Resource):
+    def list(self, property_id: int) -> AdditionalIdentifiers:
+        """List additional identifiers attached to a property."""
+        return self._client._request(
+            "GET", f"property/{property_id}/identifier/list", response_type=AdditionalIdentifiers
+        )
+
+    def add(self, property_id: int, data: AdditionalIdentifier) -> Response:
+        """Add an additional identifier to a property."""
+        return self._client._request("POST", f"property/{property_id}/identifier", data=data, response_type=Response)
+
+    def get(self, property_id: int, identifier_id: int) -> AdditionalIdentifier:
+        """Get a specific additional identifier on a property."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/identifier/{identifier_id}",
+            response_type=AdditionalIdentifier,
+        )
+
+    def update(self, property_id: int, identifier_id: int, data: AdditionalIdentifier) -> Response:
+        """Update a specific additional identifier on a property."""
+        return self._client._request(
+            "PUT",
+            f"property/{property_id}/identifier/{identifier_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    def delete(self, property_id: int, identifier_id: int) -> Response:
+        """Remove a specific additional identifier from a property."""
+        return self._client._request(
+            "DELETE",
+            f"property/{property_id}/identifier/{identifier_id}",
+            response_type=Response,
+        )
+
+    def types(self) -> AdditionalIdentifierTypes:
+        """List EPA-approved additional identifier types (catalog)."""
+        return self._client._request("GET", "property/identifier/list", response_type=AdditionalIdentifierTypes)
+
+
+class AsyncIdentifierResource(AsyncResource):
+    async def list(self, property_id: int) -> AdditionalIdentifiers:
+        return await self._client._arequest(
+            "GET", f"property/{property_id}/identifier/list", response_type=AdditionalIdentifiers
+        )
+
+    async def add(self, property_id: int, data: AdditionalIdentifier) -> Response:
+        return await self._client._arequest(
+            "POST", f"property/{property_id}/identifier", data=data, response_type=Response
+        )
+
+    async def get(self, property_id: int, identifier_id: int) -> AdditionalIdentifier:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/identifier/{identifier_id}",
+            response_type=AdditionalIdentifier,
+        )
+
+    async def update(self, property_id: int, identifier_id: int, data: AdditionalIdentifier) -> Response:
+        return await self._client._arequest(
+            "PUT",
+            f"property/{property_id}/identifier/{identifier_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    async def delete(self, property_id: int, identifier_id: int) -> Response:
+        return await self._client._arequest(
+            "DELETE",
+            f"property/{property_id}/identifier/{identifier_id}",
+            response_type=Response,
+        )
+
+    async def types(self) -> AdditionalIdentifierTypes:
+        return await self._client._arequest("GET", "property/identifier/list", response_type=AdditionalIdentifierTypes)

epa_pm_api_wrapper/resources/meter.py

@@ -0,0 +1,277 @@
+"""Meter resource — `/meter` and `/property/{propertyId}/meter` endpoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from epa_pm_api_wrapper.models import (
+    AdditionalIdentifier,
+    AdditionalIdentifiers,
+    AdditionalIdentifierTypes,
+    CustomFieldList,
+    IndividualMeter,
+    Meter,
+    Response,
+)
+
+from ._base import AsyncResource, Resource
+
+if TYPE_CHECKING:
+    from epa_pm_api_wrapper.client import EpaPmAsyncClient, EpaPmClient
+
+
+class MeterIdentifierResource(Resource):
+    """Mirrors :class:`IdentifierResource` but for meter identifiers."""
+
+    def list(self, meter_id: int) -> AdditionalIdentifiers:
+        """List additional identifiers attached to a meter."""
+        return self._client._request("GET", f"meter/{meter_id}/identifier/list", response_type=AdditionalIdentifiers)
+
+    def add(self, meter_id: int, data: AdditionalIdentifier) -> Response:
+        """Add an additional identifier to a meter."""
+        return self._client._request("POST", f"meter/{meter_id}/identifier", data=data, response_type=Response)
+
+    def get(self, meter_id: int, identifier_id: int) -> AdditionalIdentifier:
+        """Get a specific additional identifier on a meter."""
+        return self._client._request(
+            "GET",
+            f"meter/{meter_id}/identifier/{identifier_id}",
+            response_type=AdditionalIdentifier,
+        )
+
+    def update(self, meter_id: int, identifier_id: int, data: AdditionalIdentifier) -> Response:
+        """Update a specific additional identifier on a meter."""
+        return self._client._request(
+            "PUT",
+            f"meter/{meter_id}/identifier/{identifier_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    def delete(self, meter_id: int, identifier_id: int) -> Response:
+        """Remove a specific additional identifier from a meter."""
+        return self._client._request(
+            "DELETE",
+            f"meter/{meter_id}/identifier/{identifier_id}",
+            response_type=Response,
+        )
+
+    def types(self) -> AdditionalIdentifierTypes:
+        """List EPA-approved additional identifier types for meters (catalog)."""
+        return self._client._request("GET", "meter/identifier/list", response_type=AdditionalIdentifierTypes)
+
+    def list_for_property(self, property_id: int) -> AdditionalIdentifiers:
+        """List identifier values across all meters of a property."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/meter/identifier/list",
+            response_type=AdditionalIdentifiers,
+        )
+
+
+class AggregateMeterResource(Resource):
+    """Aggregation operations on a meter — get aggregate info, manage individual meters.
+
+    Note the URL split: list/add operations on the parent meter use ``/meter/{id}/...``,
+    but individual-meter records have their own top-level path ``/meter/individual/{id}``.
+    """
+
+    def get(self, meter_id: int) -> Meter:
+        """Get aggregate meter info (returns the meter with its ``aggregateMeter`` flag)."""
+        return self._client._request("GET", f"meter/{meter_id}/aggregateMeter", response_type=Meter)
+
+    def list_individuals(self, meter_id: int) -> Response:
+        """List individual meters that compose an aggregate meter."""
+        return self._client._request("GET", f"meter/{meter_id}/individual/list", response_type=Response)
+
+    def add_individual(self, meter_id: int, data: IndividualMeter) -> Response:
+        """Add an individual meter to an aggregate."""
+        return self._client._request("POST", f"meter/{meter_id}/individual", data=data, response_type=Response)
+
+    def delete_all_individuals(self, meter_id: int) -> Response:
+        """Remove every individual meter from an aggregate."""
+        return self._client._request("DELETE", f"meter/{meter_id}/individual", response_type=Response)
+
+    def get_individual(self, individual_meter_id: int) -> IndividualMeter:
+        """Get a specific individual meter record."""
+        return self._client._request("GET", f"meter/individual/{individual_meter_id}", response_type=IndividualMeter)
+
+    def update_individual(self, individual_meter_id: int, data: IndividualMeter) -> Response:
+        """Update a specific individual meter record."""
+        return self._client._request(
+            "PUT", f"meter/individual/{individual_meter_id}", data=data, response_type=Response
+        )
+
+    def delete_individual(self, individual_meter_id: int) -> Response:
+        """Remove a specific individual meter from its aggregate."""
+        return self._client._request("DELETE", f"meter/individual/{individual_meter_id}", response_type=Response)
+
+
+class MeterResource(Resource):
+    def __init__(self, client: EpaPmClient) -> None:
+        super().__init__(client)
+        self.aggregate = AggregateMeterResource(client)
+        self.identifier = MeterIdentifierResource(client)
+
+    def list(self, property_id: int, my_access_only: bool | None = None) -> Response:
+        """List meters under a property."""
+        params = {"myAccessOnly": "true" if my_access_only else "false"} if my_access_only is not None else None
+        return self._client._request("GET", f"property/{property_id}/meter/list", params=params, response_type=Response)
+
+    def get(self, meter_id: int) -> Meter:
+        """Get details for a specific meter."""
+        return self._client._request("GET", f"meter/{meter_id}", response_type=Meter)
+
+    def create(self, property_id: int, meter_data: Meter) -> Response:
+        """Add a new meter under a property."""
+        return self._client._request("POST", f"property/{property_id}/meter", data=meter_data, response_type=Response)
+
+    def update(self, meter_id: int, meter_data: Meter) -> Response:
+        """Update an existing meter."""
+        return self._client._request("PUT", f"meter/{meter_id}", data=meter_data, response_type=Response)
+
+    def delete(self, meter_id: int) -> Response:
+        """Delete a meter."""
+        return self._client._request("DELETE", f"meter/{meter_id}", response_type=Response)
+
+    def custom_fields(self, meter_id: int) -> CustomFieldList:
+        """List custom field values stored on a meter."""
+        return self._client._request("GET", f"meter/{meter_id}/customFieldList", response_type=CustomFieldList)
+
+    def what_changed(
+        self,
+        customer_id: int | None = None,
+        property_id: int | None = None,
+        date: str | None = None,
+    ) -> Response:
+        """List meters modified on/after ``date`` (YYYY-MM-DD).
+
+        Pass exactly one of ``customer_id`` (scopes to all meters under a connected
+        customer) or ``property_id`` (scopes to one property's meters).
+        """
+        if (customer_id is None) == (property_id is None):
+            raise ValueError("Pass exactly one of customer_id or property_id")
+        if date is None:
+            raise ValueError("date is required (YYYY-MM-DD)")
+        path = (
+            f"customer/{customer_id}/meter/whatChanged"
+            if customer_id is not None
+            else f"property/{property_id}/meter/whatChanged"
+        )
+        return self._client._request("GET", path, params={"date": date}, response_type=Response)
+
+
+class AsyncMeterIdentifierResource(AsyncResource):
+    async def list(self, meter_id: int) -> AdditionalIdentifiers:
+        return await self._client._arequest(
+            "GET", f"meter/{meter_id}/identifier/list", response_type=AdditionalIdentifiers
+        )
+
+    async def add(self, meter_id: int, data: AdditionalIdentifier) -> Response:
+        return await self._client._arequest("POST", f"meter/{meter_id}/identifier", data=data, response_type=Response)
+
+    async def get(self, meter_id: int, identifier_id: int) -> AdditionalIdentifier:
+        return await self._client._arequest(
+            "GET",
+            f"meter/{meter_id}/identifier/{identifier_id}",
+            response_type=AdditionalIdentifier,
+        )
+
+    async def update(self, meter_id: int, identifier_id: int, data: AdditionalIdentifier) -> Response:
+        return await self._client._arequest(
+            "PUT",
+            f"meter/{meter_id}/identifier/{identifier_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    async def delete(self, meter_id: int, identifier_id: int) -> Response:
+        return await self._client._arequest(
+            "DELETE",
+            f"meter/{meter_id}/identifier/{identifier_id}",
+            response_type=Response,
+        )
+
+    async def types(self) -> AdditionalIdentifierTypes:
+        return await self._client._arequest("GET", "meter/identifier/list", response_type=AdditionalIdentifierTypes)
+
+    async def list_for_property(self, property_id: int) -> AdditionalIdentifiers:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/meter/identifier/list",
+            response_type=AdditionalIdentifiers,
+        )
+
+
+class AsyncAggregateMeterResource(AsyncResource):
+    async def get(self, meter_id: int) -> Meter:
+        return await self._client._arequest("GET", f"meter/{meter_id}/aggregateMeter", response_type=Meter)
+
+    async def list_individuals(self, meter_id: int) -> Response:
+        return await self._client._arequest("GET", f"meter/{meter_id}/individual/list", response_type=Response)
+
+    async def add_individual(self, meter_id: int, data: IndividualMeter) -> Response:
+        return await self._client._arequest("POST", f"meter/{meter_id}/individual", data=data, response_type=Response)
+
+    async def delete_all_individuals(self, meter_id: int) -> Response:
+        return await self._client._arequest("DELETE", f"meter/{meter_id}/individual", response_type=Response)
+
+    async def get_individual(self, individual_meter_id: int) -> IndividualMeter:
+        return await self._client._arequest(
+            "GET", f"meter/individual/{individual_meter_id}", response_type=IndividualMeter
+        )
+
+    async def update_individual(self, individual_meter_id: int, data: IndividualMeter) -> Response:
+        return await self._client._arequest(
+            "PUT", f"meter/individual/{individual_meter_id}", data=data, response_type=Response
+        )
+
+    async def delete_individual(self, individual_meter_id: int) -> Response:
+        return await self._client._arequest("DELETE", f"meter/individual/{individual_meter_id}", response_type=Response)
+
+
+class AsyncMeterResource(AsyncResource):
+    def __init__(self, client: EpaPmAsyncClient) -> None:
+        super().__init__(client)
+        self.aggregate = AsyncAggregateMeterResource(client)
+        self.identifier = AsyncMeterIdentifierResource(client)
+
+    async def list(self, property_id: int, my_access_only: bool | None = None) -> Response:
+        params = {"myAccessOnly": "true" if my_access_only else "false"} if my_access_only is not None else None
+        return await self._client._arequest(
+            "GET", f"property/{property_id}/meter/list", params=params, response_type=Response
+        )
+
+    async def get(self, meter_id: int) -> Meter:
+        return await self._client._arequest("GET", f"meter/{meter_id}", response_type=Meter)
+
+    async def create(self, property_id: int, meter_data: Meter) -> Response:
+        return await self._client._arequest(
+            "POST", f"property/{property_id}/meter", data=meter_data, response_type=Response
+        )
+
+    async def update(self, meter_id: int, meter_data: Meter) -> Response:
+        return await self._client._arequest("PUT", f"meter/{meter_id}", data=meter_data, response_type=Response)
+
+    async def delete(self, meter_id: int) -> Response:
+        return await self._client._arequest("DELETE", f"meter/{meter_id}", response_type=Response)
+
+    async def custom_fields(self, meter_id: int) -> CustomFieldList:
+        return await self._client._arequest("GET", f"meter/{meter_id}/customFieldList", response_type=CustomFieldList)
+
+    async def what_changed(
+        self,
+        customer_id: int | None = None,
+        property_id: int | None = None,
+        date: str | None = None,
+    ) -> Response:
+        if (customer_id is None) == (property_id is None):
+            raise ValueError("Pass exactly one of customer_id or property_id")
+        if date is None:
+            raise ValueError("date is required (YYYY-MM-DD)")
+        path = (
+            f"customer/{customer_id}/meter/whatChanged"
+            if customer_id is not None
+            else f"property/{property_id}/meter/whatChanged"
+        )
+        return await self._client._arequest("GET", path, params={"date": date}, response_type=Response)

epa_pm_api_wrapper/resources/metrics.py

@@ -0,0 +1,185 @@
+"""Property metrics resource — `/property/{propertyId}/metrics*` and
+`/property/{propertyId}/reasonsFor*` endpoints.
+
+All four metric endpoints take the metric specification via the ``PM-Metrics``
+HTTP header (comma-separated list of metric names — the same names returned by
+``client.report.metrics``). ``measurementSystem`` is a query param; valid values
+include "EPA" and "EU". Each endpoint validates which metric names it accepts,
+so a metric valid for ``/metrics`` may be rejected by ``/metrics/monthly``.
+"""
+
+from __future__ import annotations
+
+from epa_pm_api_wrapper.models import Alerts, PropertyMetrics
+
+from ._base import AsyncResource, Resource
+
+
+def _metric_header(metrics: list[str] | str) -> str:
+    return metrics if isinstance(metrics, str) else ",".join(metrics)
+
+
+class MetricsResource(Resource):
+    def get(
+        self,
+        property_id: int,
+        metrics: list[str] | str,
+        year: int,
+        month: int,
+        measurement_system: str = "EPA",
+    ) -> PropertyMetrics:
+        """Get period-ending metric values for a property."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/metrics",
+            params={"year": year, "month": month, "measurementSystem": measurement_system},
+            extra_headers={"PM-Metrics": _metric_header(metrics)},
+            response_type=PropertyMetrics,
+        )
+
+    def monthly(
+        self,
+        property_id: int,
+        metrics: list[str] | str,
+        year: int,
+        month: int,
+        measurement_system: str = "EPA",
+    ) -> PropertyMetrics:
+        """Get monthly metric values for a property."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/metrics/monthly",
+            params={"year": year, "month": month, "measurementSystem": measurement_system},
+            extra_headers={"PM-Metrics": _metric_header(metrics)},
+            response_type=PropertyMetrics,
+        )
+
+    def use_details(
+        self,
+        property_id: int,
+        metrics: list[str] | str,
+        year: int,
+        month: int,
+        measurement_system: str = "EPA",
+    ) -> PropertyMetrics:
+        """Get time-weighted use-detail metric values for a property."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/useDetails/metrics",
+            params={"year": year, "month": month, "measurementSystem": measurement_system},
+            extra_headers={"PM-Metrics": _metric_header(metrics)},
+            response_type=PropertyMetrics,
+        )
+
+    def design(
+        self,
+        property_id: int,
+        metrics: list[str] | str,
+        measurement_system: str = "EPA",
+    ) -> PropertyMetrics:
+        """Get metric values for a property design (no time period)."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/design/metrics",
+            params={"measurementSystem": measurement_system},
+            extra_headers={"PM-Metrics": _metric_header(metrics)},
+            response_type=PropertyMetrics,
+        )
+
+    def reasons_for_no_score(self, property_id: int, year: int, month: int) -> Alerts:
+        """Explain why a property cannot receive an ENERGY STAR score for a period."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/reasonsForNoScore",
+            params={"year": year, "month": month},
+            response_type=Alerts,
+        )
+
+    def reasons_for_no_water_score(self, property_id: int, year: int, month: int) -> Alerts:
+        """Explain why a property cannot receive an ENERGY STAR water score for a period."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/reasonsForNoWaterScore",
+            params={"year": year, "month": month},
+            response_type=Alerts,
+        )
+
+
+class AsyncMetricsResource(AsyncResource):
+    async def get(
+        self,
+        property_id: int,
+        metrics: list[str] | str,
+        year: int,
+        month: int,
+        measurement_system: str = "EPA",
+    ) -> PropertyMetrics:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/metrics",
+            params={"year": year, "month": month, "measurementSystem": measurement_system},
+            extra_headers={"PM-Metrics": _metric_header(metrics)},
+            response_type=PropertyMetrics,
+        )
+
+    async def monthly(
+        self,
+        property_id: int,
+        metrics: list[str] | str,
+        year: int,
+        month: int,
+        measurement_system: str = "EPA",
+    ) -> PropertyMetrics:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/metrics/monthly",
+            params={"year": year, "month": month, "measurementSystem": measurement_system},
+            extra_headers={"PM-Metrics": _metric_header(metrics)},
+            response_type=PropertyMetrics,
+        )
+
+    async def use_details(
+        self,
+        property_id: int,
+        metrics: list[str] | str,
+        year: int,
+        month: int,
+        measurement_system: str = "EPA",
+    ) -> PropertyMetrics:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/useDetails/metrics",
+            params={"year": year, "month": month, "measurementSystem": measurement_system},
+            extra_headers={"PM-Metrics": _metric_header(metrics)},
+            response_type=PropertyMetrics,
+        )
+
+    async def design(
+        self,
+        property_id: int,
+        metrics: list[str] | str,
+        measurement_system: str = "EPA",
+    ) -> PropertyMetrics:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/design/metrics",
+            params={"measurementSystem": measurement_system},
+            extra_headers={"PM-Metrics": _metric_header(metrics)},
+            response_type=PropertyMetrics,
+        )
+
+    async def reasons_for_no_score(self, property_id: int, year: int, month: int) -> Alerts:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/reasonsForNoScore",
+            params={"year": year, "month": month},
+            response_type=Alerts,
+        )
+
+    async def reasons_for_no_water_score(self, property_id: int, year: int, month: int) -> Alerts:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/reasonsForNoWaterScore",
+            params={"year": year, "month": month},
+            response_type=Alerts,
+        )