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

epa_pm_api_wrapper/resources/consumption_data.py

@@ -0,0 +1,142 @@
+"""Consumption data resource — `/meter/{meterId}/consumptionData` and
+`/consumptionData/{id}` endpoints."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+
+from epa_pm_api_wrapper.models import MeterConsumption, MeterData, Response
+
+from ._base import AsyncResource, Resource
+
+
+class ConsumptionDataResource(Resource):
+    def get(
+        self,
+        meter_id: int,
+        page: int | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> MeterData:
+        """Get consumption data for a meter.
+
+        Returns up to 120 records per call; use ``page`` to paginate. Dates are ISO 8601
+        (YYYY-MM-DD) strings.
+        """
+        params = {"page": page, "startDate": start_date, "endDate": end_date}
+        return self._client._request("GET", f"meter/{meter_id}/consumptionData", params=params, response_type=MeterData)
+
+    def add(self, meter_id: int, data: MeterData) -> Response:
+        """Add consumption data records to a meter."""
+        return self._client._request("POST", f"meter/{meter_id}/consumptionData", data=data, response_type=Response)
+
+    def update(self, consumption_data_id: int, data: MeterConsumption) -> Response:
+        """Update a single consumption data record."""
+        return self._client._request("PUT", f"consumptionData/{consumption_data_id}", data=data, response_type=Response)
+
+    def delete(self, consumption_data_id: int) -> Response:
+        """Delete a single consumption data record."""
+        return self._client._request("DELETE", f"consumptionData/{consumption_data_id}", response_type=Response)
+
+    def delete_range(self, meter_id: int, start_date: str, end_date: str) -> Response:
+        """Delete consumption records on a meter within an inclusive date range (YYYY-MM-DD)."""
+        return self._client._request(
+            "DELETE",
+            f"meter/{meter_id}/consumptionData",
+            params={"startDate": start_date, "endDate": end_date},
+            response_type=Response,
+        )
+
+    def what_changed(self, customer_id: int, date: str) -> Response:
+        """List meters under a connected customer with consumption data modified on/after ``date``."""
+        return self._client._request(
+            "GET",
+            f"customer/{customer_id}/meter/consumptionData/whatChanged",
+            params={"date": date},
+            response_type=Response,
+        )
+
+    def iter(
+        self,
+        meter_id: int,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> Iterator[MeterConsumption]:
+        """Iterate over every consumption record for a meter, paging internally.
+
+        The EPA API returns up to 120 records per page; this helper walks pages
+        starting at 1 until an empty page is returned. Yields one
+        :class:`MeterConsumption` at a time so the caller never has to think
+        about page boundaries::
+
+            for record in client.consumption_data.iter(meter_id, start_date="2024-01-01"):
+                process(record)
+        """
+        page = 1
+        while True:
+            data = self.get(meter_id, page=page, start_date=start_date, end_date=end_date)
+            records = data.meter_consumption or []
+            if not records:
+                return
+            yield from records
+            page += 1
+
+
+class AsyncConsumptionDataResource(AsyncResource):
+    async def get(
+        self,
+        meter_id: int,
+        page: int | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> MeterData:
+        params = {"page": page, "startDate": start_date, "endDate": end_date}
+        return await self._client._arequest(
+            "GET", f"meter/{meter_id}/consumptionData", params=params, response_type=MeterData
+        )
+
+    async def add(self, meter_id: int, data: MeterData) -> Response:
+        return await self._client._arequest(
+            "POST", f"meter/{meter_id}/consumptionData", data=data, response_type=Response
+        )
+
+    async def update(self, consumption_data_id: int, data: MeterConsumption) -> Response:
+        return await self._client._arequest(
+            "PUT", f"consumptionData/{consumption_data_id}", data=data, response_type=Response
+        )
+
+    async def delete(self, consumption_data_id: int) -> Response:
+        return await self._client._arequest("DELETE", f"consumptionData/{consumption_data_id}", response_type=Response)
+
+    async def delete_range(self, meter_id: int, start_date: str, end_date: str) -> Response:
+        return await self._client._arequest(
+            "DELETE",
+            f"meter/{meter_id}/consumptionData",
+            params={"startDate": start_date, "endDate": end_date},
+            response_type=Response,
+        )
+
+    async def what_changed(self, customer_id: int, date: str) -> Response:
+        return await self._client._arequest(
+            "GET",
+            f"customer/{customer_id}/meter/consumptionData/whatChanged",
+            params={"date": date},
+            response_type=Response,
+        )
+
+    async def iter(
+        self,
+        meter_id: int,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> AsyncIterator[MeterConsumption]:
+        """Async equivalent of :meth:`ConsumptionDataResource.iter`."""
+        page = 1
+        while True:
+            data = await self.get(meter_id, page=page, start_date=start_date, end_date=end_date)
+            records = data.meter_consumption or []
+            if not records:
+                return
+            for record in records:
+                yield record
+            page += 1

epa_pm_api_wrapper/resources/custom_metric.py

@@ -0,0 +1,91 @@
+"""Custom metrics resource — `/property/{propertyId}/customMetrics` endpoints.
+
+Custom metrics are user-defined formulas computed from existing metrics and
+property use details, addressed by a 1-based ``slot`` integer per property.
+"""
+
+from __future__ import annotations
+
+from epa_pm_api_wrapper.models import CustomMetric, DetailsTypes, Response
+
+from ._base import AsyncResource, Resource
+
+
+class CustomMetricResource(Resource):
+    def list(self, property_id: int) -> Response:
+        """List all custom metric slots defined for a property."""
+        return self._client._request("GET", f"property/{property_id}/customMetrics", response_type=Response)
+
+    def get(self, property_id: int, slot: int) -> CustomMetric:
+        """Get the custom metric defined in a specific slot."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/customMetrics/{slot}",
+            response_type=CustomMetric,
+        )
+
+    def create(self, property_id: int, slot: int, data: CustomMetric) -> Response:
+        """Define a new custom metric in the given slot."""
+        return self._client._request(
+            "POST",
+            f"property/{property_id}/customMetrics/{slot}",
+            data=data,
+            response_type=Response,
+        )
+
+    def update(self, property_id: int, slot: int, data: CustomMetric) -> Response:
+        """Update the custom metric in the given slot."""
+        return self._client._request(
+            "PUT",
+            f"property/{property_id}/customMetrics/{slot}",
+            data=data,
+            response_type=Response,
+        )
+
+    def delete(self, property_id: int, slot: int) -> Response:
+        """Remove the custom metric from the given slot."""
+        return self._client._request(
+            "DELETE",
+            f"property/{property_id}/customMetrics/{slot}",
+            response_type=Response,
+        )
+
+    def available_use_detail_types(self, property_id: int) -> DetailsTypes:
+        """List the property-use detail types usable in custom metric definitions."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/customMetrics/availableUseDetailTypes",
+            response_type=DetailsTypes,
+        )
+
+
+class AsyncCustomMetricResource(AsyncResource):
+    async def list(self, property_id: int) -> Response:
+        return await self._client._arequest("GET", f"property/{property_id}/customMetrics", response_type=Response)
+
+    async def get(self, property_id: int, slot: int) -> CustomMetric:
+        return await self._client._arequest(
+            "GET", f"property/{property_id}/customMetrics/{slot}", response_type=CustomMetric
+        )
+
+    async def create(self, property_id: int, slot: int, data: CustomMetric) -> Response:
+        return await self._client._arequest(
+            "POST", f"property/{property_id}/customMetrics/{slot}", data=data, response_type=Response
+        )
+
+    async def update(self, property_id: int, slot: int, data: CustomMetric) -> Response:
+        return await self._client._arequest(
+            "PUT", f"property/{property_id}/customMetrics/{slot}", data=data, response_type=Response
+        )
+
+    async def delete(self, property_id: int, slot: int) -> Response:
+        return await self._client._arequest(
+            "DELETE", f"property/{property_id}/customMetrics/{slot}", response_type=Response
+        )
+
+    async def available_use_detail_types(self, property_id: int) -> DetailsTypes:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/customMetrics/availableUseDetailTypes",
+            response_type=DetailsTypes,
+        )

epa_pm_api_wrapper/resources/customer.py

@@ -0,0 +1,45 @@
+"""Customer resource — `/customer` endpoints (the authenticated account's connected customers)."""
+
+from __future__ import annotations
+
+from epa_pm_api_wrapper.models import Customer, Response
+
+from ._base import AsyncResource, Resource
+
+
+class CustomerResource(Resource):
+    def list(self) -> Response:
+        """List customers connected to the authenticated account."""
+        return self._client._request("GET", "customer/list", response_type=Response)
+
+    def get(self, customer_id: int) -> Customer:
+        """Get a connected customer's account info."""
+        return self._client._request("GET", f"customer/{customer_id}", response_type=Customer)
+
+    def create(self, customer_data: Customer) -> Response:
+        """Create a new customer account linked to the authenticated organization (data-exchange providers only)."""
+        return self._client._request("POST", "customer", data=customer_data, response_type=Response)
+
+    def update(self, customer_id: int, customer_data: Customer) -> Response:
+        """Update a connected customer's account."""
+        return self._client._request("PUT", f"customer/{customer_id}", data=customer_data, response_type=Response)
+
+
+class AsyncCustomerResource(AsyncResource):
+    async def list(self) -> Response:
+        """List customers connected to the authenticated account."""
+        return await self._client._arequest("GET", "customer/list", response_type=Response)
+
+    async def get(self, customer_id: int) -> Customer:
+        """Get a connected customer's account info."""
+        return await self._client._arequest("GET", f"customer/{customer_id}", response_type=Customer)
+
+    async def create(self, customer_data: Customer) -> Response:
+        """Create a new customer account linked to the authenticated organization (data-exchange providers only)."""
+        return await self._client._arequest("POST", "customer", data=customer_data, response_type=Response)
+
+    async def update(self, customer_id: int, customer_data: Customer) -> Response:
+        """Update a connected customer's account."""
+        return await self._client._arequest(
+            "PUT", f"customer/{customer_id}", data=customer_data, response_type=Response
+        )

epa_pm_api_wrapper/resources/data_exchange.py

@@ -0,0 +1,111 @@
+"""Data-exchange settings resource — `/dataExchangeSettings` endpoints.
+
+Used by data-exchange providers (organizations that maintain customer accounts)
+to configure their offering and define custom fields collected at customer
+connection time. Custom field *values* on individual accounts/properties/meters
+are exposed via the ``custom_fields`` method on those resources.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from epa_pm_api_wrapper.models import (
+    CustomField,
+    DataExchangeSettings,
+    Response,
+)
+
+from ._base import AsyncResource, Resource
+
+if TYPE_CHECKING:
+    from epa_pm_api_wrapper.client import EpaPmAsyncClient, EpaPmClient
+
+
+class DataExchangeCustomFieldsResource(Resource):
+    def list(self) -> Response:
+        """List the custom fields defined in your data-exchange settings."""
+        return self._client._request("GET", "dataExchangeSettings/customField/list", response_type=Response)
+
+    def create(self, data: CustomField) -> Response:
+        """Define a new custom field in your data-exchange settings."""
+        return self._client._request("POST", "dataExchangeSettings/customField", data=data, response_type=Response)
+
+    def get(self, custom_field_id: int) -> CustomField:
+        """Get a custom field definition."""
+        return self._client._request(
+            "GET",
+            f"dataExchangeSettings/customField/{custom_field_id}",
+            response_type=CustomField,
+        )
+
+    def update(self, custom_field_id: int, data: CustomField) -> Response:
+        """Update a custom field definition."""
+        return self._client._request(
+            "PUT",
+            f"dataExchangeSettings/customField/{custom_field_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    def delete(self, custom_field_id: int) -> Response:
+        """Remove a custom field definition."""
+        return self._client._request(
+            "DELETE",
+            f"dataExchangeSettings/customField/{custom_field_id}",
+            response_type=Response,
+        )
+
+
+class DataExchangeResource(Resource):
+    def __init__(self, client: EpaPmClient) -> None:
+        super().__init__(client)
+        self.custom_fields = DataExchangeCustomFieldsResource(client)
+
+    def get(self) -> DataExchangeSettings:
+        """Get your data-exchange settings."""
+        return self._client._request("GET", "dataExchangeSettings", response_type=DataExchangeSettings)
+
+    def update(self, data: DataExchangeSettings) -> Response:
+        """Update your data-exchange settings."""
+        return self._client._request("PUT", "dataExchangeSettings", data=data, response_type=Response)
+
+
+class AsyncDataExchangeCustomFieldsResource(AsyncResource):
+    async def list(self) -> Response:
+        return await self._client._arequest("GET", "dataExchangeSettings/customField/list", response_type=Response)
+
+    async def create(self, data: CustomField) -> Response:
+        return await self._client._arequest(
+            "POST", "dataExchangeSettings/customField", data=data, response_type=Response
+        )
+
+    async def get(self, custom_field_id: int) -> CustomField:
+        return await self._client._arequest(
+            "GET", f"dataExchangeSettings/customField/{custom_field_id}", response_type=CustomField
+        )
+
+    async def update(self, custom_field_id: int, data: CustomField) -> Response:
+        return await self._client._arequest(
+            "PUT",
+            f"dataExchangeSettings/customField/{custom_field_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    async def delete(self, custom_field_id: int) -> Response:
+        return await self._client._arequest(
+            "DELETE", f"dataExchangeSettings/customField/{custom_field_id}", response_type=Response
+        )
+
+
+class AsyncDataExchangeResource(AsyncResource):
+    def __init__(self, client: EpaPmAsyncClient) -> None:
+        super().__init__(client)
+        self.custom_fields = AsyncDataExchangeCustomFieldsResource(client)
+
+    async def get(self) -> DataExchangeSettings:
+        return await self._client._arequest("GET", "dataExchangeSettings", response_type=DataExchangeSettings)
+
+    async def update(self, data: DataExchangeSettings) -> Response:
+        return await self._client._arequest("PUT", "dataExchangeSettings", data=data, response_type=Response)

epa_pm_api_wrapper/resources/green_power.py

@@ -0,0 +1,237 @@
+"""Green power resource — offsite purchases and onsite renewable generation.
+
+Two sub-namespaces:
+
+- ``green_power.offsite`` for purchased green power
+  (``/property/{id}/offsiteGreenPowerPurchases`` and
+  ``/offsiteGreenPowerPurchases/{id}``)
+- ``green_power.onsite`` for onsite solar/wind meter generation details
+  (``/meter/{id}/onsiteRenewableDetails`` and
+  ``/meter/{id}/onsiteRenewableOptionalInfo``)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from epa_pm_api_wrapper.models import (
+    OffsiteGreenPowerPurchase,
+    OnsiteRenewableDetail,
+    OnsiteRenewableDetails,
+    OnsiteRenewableOptionalInfo,
+    Response,
+)
+
+from ._base import AsyncResource, Resource
+
+if TYPE_CHECKING:
+    from epa_pm_api_wrapper.client import EpaPmAsyncClient, EpaPmClient
+
+
+class OffsiteGreenPowerResource(Resource):
+    def list(self, property_id: int) -> Response:
+        """List offsite green power purchases for a property."""
+        return self._client._request(
+            "GET",
+            f"property/{property_id}/offsiteGreenPowerPurchases",
+            response_type=Response,
+        )
+
+    def add(self, property_id: int, data: OffsiteGreenPowerPurchase) -> Response:
+        """Add an offsite green power purchase to a property."""
+        return self._client._request(
+            "POST",
+            f"property/{property_id}/offsiteGreenPowerPurchases",
+            data=data,
+            response_type=Response,
+        )
+
+    def get(self, purchase_id: int) -> OffsiteGreenPowerPurchase:
+        """Get a specific offsite green power purchase."""
+        return self._client._request(
+            "GET",
+            f"offsiteGreenPowerPurchases/{purchase_id}",
+            response_type=OffsiteGreenPowerPurchase,
+        )
+
+    def update(self, purchase_id: int, data: OffsiteGreenPowerPurchase) -> Response:
+        """Update an offsite green power purchase."""
+        return self._client._request(
+            "PUT",
+            f"offsiteGreenPowerPurchases/{purchase_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    def delete(self, purchase_id: int) -> Response:
+        """Delete an offsite green power purchase."""
+        return self._client._request("DELETE", f"offsiteGreenPowerPurchases/{purchase_id}", response_type=Response)
+
+
+class OnsiteRenewableResource(Resource):
+    def list_details(self, meter_id: int) -> OnsiteRenewableDetails:
+        """List onsite renewable detail records for a solar/wind meter (1000 per call)."""
+        return self._client._request(
+            "GET",
+            f"meter/{meter_id}/onsiteRenewableDetails",
+            response_type=OnsiteRenewableDetails,
+        )
+
+    def add_detail(self, meter_id: int, data: OnsiteRenewableDetail) -> Response:
+        """Add an onsite renewable detail record to a meter."""
+        return self._client._request(
+            "POST",
+            f"meter/{meter_id}/onsiteRenewableDetails",
+            data=data,
+            response_type=Response,
+        )
+
+    def get_detail(self, detail_id: int) -> OnsiteRenewableDetail:
+        """Get a specific onsite renewable detail record."""
+        return self._client._request("GET", f"onsiteRenewableDetails/{detail_id}", response_type=OnsiteRenewableDetail)
+
+    def update_detail(self, detail_id: int, data: OnsiteRenewableDetail) -> Response:
+        """Update a specific onsite renewable detail record."""
+        return self._client._request(
+            "PUT",
+            f"onsiteRenewableDetails/{detail_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    def delete_detail(self, detail_id: int) -> Response:
+        """Delete a specific onsite renewable detail record."""
+        return self._client._request("DELETE", f"onsiteRenewableDetails/{detail_id}", response_type=Response)
+
+    def get_optional_info(self, meter_id: int) -> OnsiteRenewableOptionalInfo:
+        """Get optional onsite renewable info attached to a meter."""
+        return self._client._request(
+            "GET",
+            f"meter/{meter_id}/onsiteRenewableOptionalInfo",
+            response_type=OnsiteRenewableOptionalInfo,
+        )
+
+    def create_optional_info(self, meter_id: int, data: OnsiteRenewableOptionalInfo) -> Response:
+        """Add optional onsite renewable info to a meter."""
+        return self._client._request(
+            "POST",
+            f"meter/{meter_id}/onsiteRenewableOptionalInfo",
+            data=data,
+            response_type=Response,
+        )
+
+    def update_optional_info(self, meter_id: int, data: OnsiteRenewableOptionalInfo) -> Response:
+        """Update optional onsite renewable info on a meter."""
+        return self._client._request(
+            "PUT",
+            f"meter/{meter_id}/onsiteRenewableOptionalInfo",
+            data=data,
+            response_type=Response,
+        )
+
+
+class GreenPowerResource(Resource):
+    def __init__(self, client: EpaPmClient) -> None:
+        super().__init__(client)
+        self.offsite = OffsiteGreenPowerResource(client)
+        self.onsite = OnsiteRenewableResource(client)
+
+
+class AsyncOffsiteGreenPowerResource(AsyncResource):
+    async def list(self, property_id: int) -> Response:
+        return await self._client._arequest(
+            "GET",
+            f"property/{property_id}/offsiteGreenPowerPurchases",
+            response_type=Response,
+        )
+
+    async def add(self, property_id: int, data: OffsiteGreenPowerPurchase) -> Response:
+        return await self._client._arequest(
+            "POST",
+            f"property/{property_id}/offsiteGreenPowerPurchases",
+            data=data,
+            response_type=Response,
+        )
+
+    async def get(self, purchase_id: int) -> OffsiteGreenPowerPurchase:
+        return await self._client._arequest(
+            "GET",
+            f"offsiteGreenPowerPurchases/{purchase_id}",
+            response_type=OffsiteGreenPowerPurchase,
+        )
+
+    async def update(self, purchase_id: int, data: OffsiteGreenPowerPurchase) -> Response:
+        return await self._client._arequest(
+            "PUT",
+            f"offsiteGreenPowerPurchases/{purchase_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    async def delete(self, purchase_id: int) -> Response:
+        return await self._client._arequest(
+            "DELETE", f"offsiteGreenPowerPurchases/{purchase_id}", response_type=Response
+        )
+
+
+class AsyncOnsiteRenewableResource(AsyncResource):
+    async def list_details(self, meter_id: int) -> OnsiteRenewableDetails:
+        return await self._client._arequest(
+            "GET",
+            f"meter/{meter_id}/onsiteRenewableDetails",
+            response_type=OnsiteRenewableDetails,
+        )
+
+    async def add_detail(self, meter_id: int, data: OnsiteRenewableDetail) -> Response:
+        return await self._client._arequest(
+            "POST",
+            f"meter/{meter_id}/onsiteRenewableDetails",
+            data=data,
+            response_type=Response,
+        )
+
+    async def get_detail(self, detail_id: int) -> OnsiteRenewableDetail:
+        return await self._client._arequest(
+            "GET", f"onsiteRenewableDetails/{detail_id}", response_type=OnsiteRenewableDetail
+        )
+
+    async def update_detail(self, detail_id: int, data: OnsiteRenewableDetail) -> Response:
+        return await self._client._arequest(
+            "PUT",
+            f"onsiteRenewableDetails/{detail_id}",
+            data=data,
+            response_type=Response,
+        )
+
+    async def delete_detail(self, detail_id: int) -> Response:
+        return await self._client._arequest("DELETE", f"onsiteRenewableDetails/{detail_id}", response_type=Response)
+
+    async def get_optional_info(self, meter_id: int) -> OnsiteRenewableOptionalInfo:
+        return await self._client._arequest(
+            "GET",
+            f"meter/{meter_id}/onsiteRenewableOptionalInfo",
+            response_type=OnsiteRenewableOptionalInfo,
+        )
+
+    async def create_optional_info(self, meter_id: int, data: OnsiteRenewableOptionalInfo) -> Response:
+        return await self._client._arequest(
+            "POST",
+            f"meter/{meter_id}/onsiteRenewableOptionalInfo",
+            data=data,
+            response_type=Response,
+        )
+
+    async def update_optional_info(self, meter_id: int, data: OnsiteRenewableOptionalInfo) -> Response:
+        return await self._client._arequest(
+            "PUT",
+            f"meter/{meter_id}/onsiteRenewableOptionalInfo",
+            data=data,
+            response_type=Response,
+        )
+
+
+class AsyncGreenPowerResource(AsyncResource):
+    def __init__(self, client: EpaPmAsyncClient) -> None:
+        super().__init__(client)
+        self.offsite = AsyncOffsiteGreenPowerResource(client)
+        self.onsite = AsyncOnsiteRenewableResource(client)

epa_pm_api_wrapper/resources/hey.py

@@ -0,0 +1,22 @@
+"""Home Energy Yardstick resource — `/hey` endpoint.
+
+Single endpoint: ``POST /hey``. Returns scoring metrics for a residential
+property based on the supplied design and meter data. Test environment only.
+"""
+
+from __future__ import annotations
+
+from epa_pm_api_wrapper.models import Hey, PropertyMetrics
+
+from ._base import AsyncResource, Resource
+
+
+class HeyResource(Resource):
+    def evaluate(self, design: Hey) -> PropertyMetrics:
+        """Run Home Energy Yardstick against the supplied design and meter data."""
+        return self._client._request("POST", "hey", data=design, response_type=PropertyMetrics)
+
+
+class AsyncHeyResource(AsyncResource):
+    async def evaluate(self, design: Hey) -> PropertyMetrics:
+        return await self._client._arequest("POST", "hey", data=design, response_type=PropertyMetrics)