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

epa_pm_api_wrapper/resources/property_use.py

@@ -0,0 +1,277 @@
+"""Property use resource — `/propertyUse`, `/useDetails`, and `/customUse` endpoints.
+
+Sub-namespaces:
+
+- ``client.property_use.use_details`` for use-detail revisions
+  (``/propertyUse/{id}/useDetails``, ``/useDetails/{id}``, and the revision listing)
+- ``client.property_use.custom_use`` for property-level user-defined details
+  (``/customUse/{propertyId}/...``, ``/customUse/details/{id}``)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from epa_pm_api_wrapper.models import (
+    CustomUse,
+    CustomUseDetailsType,
+    PropertyUse,
+    Response,
+    UseAttributeBase,
+    UseDetails,
+)
+
+from ._base import AsyncResource, Resource
+
+if TYPE_CHECKING:
+    from epa_pm_api_wrapper.client import EpaPmAsyncClient, EpaPmClient
+
+
+class UseDetailsResource(Resource):
+    """Use-detail revisions for a property use.
+
+    Each ``add_revision`` call creates a new dated revision; the list endpoint
+    returns the revision history within an optional date window.
+    """
+
+    def add_revision(self, property_use_id: int, data: UseDetails) -> Response:
+        """Add a new use-detail revision to a property use."""
+        return self._client._request(
+            "POST", f"propertyUse/{property_use_id}/useDetails", data=data, response_type=Response
+        )
+
+    def revisions(
+        self,
+        property_use_id: int,
+        current_as_of_start: str | None = None,
+        current_as_of_end: str | None = None,
+    ) -> Response:
+        """List historical revisions of use details for a property use within a date window."""
+        return self._client._request(
+            "GET",
+            f"propertyUse/{property_use_id}/useDetailsRevisions",
+            params={"currentAsOfStart": current_as_of_start, "currentAsOfEnd": current_as_of_end},
+            response_type=Response,
+        )
+
+    def get(self, use_details_id: int) -> UseAttributeBase:
+        """Get a single use-details record by ID.
+
+        The body is a single use-detail element (e.g. ``<numberOfComputers>``,
+        ``<totalGrossFloorArea>``); xsdata resolves the root element to the
+        matching concrete subtype. The declared return type is
+        :class:`UseAttributeBase` (the shared base) for typing convenience.
+        """
+        return cast(UseAttributeBase, self._client._request_polymorphic("GET", f"useDetails/{use_details_id}"))
+
+    def update(self, use_details_id: int, data: UseDetails) -> Response:
+        """Correct a single use-details record."""
+        return self._client._request("PUT", f"useDetails/{use_details_id}", data=data, response_type=Response)
+
+    def what_changed(self, customer_id: int, date: str) -> Response:
+        """List a connected customer's use-detail records modified on/after ``date``."""
+        return self._client._request(
+            "GET",
+            f"customer/{customer_id}/useDetails/whatChanged",
+            params={"date": date},
+            response_type=Response,
+        )
+
+
+class CustomUseResource(Resource):
+    """User-defined property-use tracking attached to a property as a whole."""
+
+    def get(self, property_id: int) -> CustomUse:
+        """Get the custom-use record (if any) for a property."""
+        return self._client._request("GET", f"customUse/{property_id}", response_type=CustomUse)
+
+    def revisions(
+        self,
+        property_id: int,
+        current_as_of_start: str | None = None,
+        current_as_of_end: str | None = None,
+    ) -> Response:
+        """List the revision history for custom-use details on a property."""
+        return self._client._request(
+            "GET",
+            f"customUse/{property_id}/detailRevisions",
+            params={"currentAsOfStart": current_as_of_start, "currentAsOfEnd": current_as_of_end},
+            response_type=Response,
+        )
+
+    def add_revision(self, property_id: int, data: CustomUse) -> Response:
+        """Add a new revision of custom-use details to a property."""
+        return self._client._request("POST", f"customUse/{property_id}/details", data=data, response_type=Response)
+
+    def get_detail(self, detail_id: int) -> CustomUseDetailsType:
+        """Get a specific custom-use detail record.
+
+        Returns ``<customUseDetail1>`` or ``<customUseDetail2>``; xsdata
+        resolves the root element to the matching concrete subtype. Declared
+        as :class:`CustomUseDetailsType` (the shared base).
+        """
+        return cast(
+            CustomUseDetailsType,
+            self._client._request_polymorphic("GET", f"customUse/details/{detail_id}"),
+        )
+
+    def update_detail(self, detail_id: int, data: CustomUse) -> Response:
+        """Update a specific custom-use detail record."""
+        return self._client._request("PUT", f"customUse/details/{detail_id}", data=data, response_type=Response)
+
+    def delete_detail(self, detail_id: int) -> Response:
+        """Delete a specific custom-use detail record."""
+        return self._client._request("DELETE", f"customUse/details/{detail_id}", response_type=Response)
+
+
+class PropertyUseResource(Resource):
+    def __init__(self, client: EpaPmClient) -> None:
+        super().__init__(client)
+        self.use_details = UseDetailsResource(client)
+        self.custom_use = CustomUseResource(client)
+
+    def list(self, property_id: int) -> Response:
+        """List property uses under a property."""
+        return self._client._request("GET", f"property/{property_id}/propertyUse/list", response_type=Response)
+
+    def create(self, property_id: int, data: PropertyUse) -> Response:
+        """Create a new property use under a property.
+
+        ``data`` is the concrete property-use subtype (Office, Hotel,
+        VehicleDealership, etc.). xsdata serializes the matching root element.
+        """
+        return self._client._request("POST", f"property/{property_id}/propertyUse", data=data, response_type=Response)
+
+    def what_changed(self, customer_id: int, date: str) -> Response:
+        """List property uses under a connected customer modified on/after the given date (YYYY-MM-DD)."""
+        return self._client._request(
+            "GET",
+            f"customer/{customer_id}/propertyUse/whatChanged",
+            params={"date": date},
+            response_type=Response,
+        )
+
+    def get(self, property_use_id: int) -> PropertyUse:
+        """Get details for a specific property use.
+
+        The API returns a use-specific element (e.g. ``<vehicleDealership>``,
+        ``<office>``, ``<hotel>``); xsdata resolves the root element to the
+        matching concrete subtype. The declared return type is
+        :class:`PropertyUse` for typing convenience.
+        """
+        return cast(PropertyUse, self._client._request_polymorphic("GET", f"propertyUse/{property_use_id}"))
+
+    def update(self, property_use_id: int, data: PropertyUse) -> Response:
+        """Update a property use's name."""
+        return self._client._request("PUT", f"propertyUse/{property_use_id}", data=data, response_type=Response)
+
+    def delete(self, property_use_id: int) -> Response:
+        """Delete a property use."""
+        return self._client._request("DELETE", f"propertyUse/{property_use_id}", response_type=Response)
+
+
+class AsyncUseDetailsResource(AsyncResource):
+    async def add_revision(self, property_use_id: int, data: UseDetails) -> Response:
+        return await self._client._arequest(
+            "POST", f"propertyUse/{property_use_id}/useDetails", data=data, response_type=Response
+        )
+
+    async def revisions(
+        self,
+        property_use_id: int,
+        current_as_of_start: str | None = None,
+        current_as_of_end: str | None = None,
+    ) -> Response:
+        return await self._client._arequest(
+            "GET",
+            f"propertyUse/{property_use_id}/useDetailsRevisions",
+            params={"currentAsOfStart": current_as_of_start, "currentAsOfEnd": current_as_of_end},
+            response_type=Response,
+        )
+
+    async def get(self, use_details_id: int) -> UseAttributeBase:
+        return cast(
+            UseAttributeBase,
+            await self._client._arequest_polymorphic("GET", f"useDetails/{use_details_id}"),
+        )
+
+    async def update(self, use_details_id: int, data: UseDetails) -> Response:
+        return await self._client._arequest("PUT", f"useDetails/{use_details_id}", data=data, response_type=Response)
+
+    async def what_changed(self, customer_id: int, date: str) -> Response:
+        return await self._client._arequest(
+            "GET",
+            f"customer/{customer_id}/useDetails/whatChanged",
+            params={"date": date},
+            response_type=Response,
+        )
+
+
+class AsyncCustomUseResource(AsyncResource):
+    async def get(self, property_id: int) -> CustomUse:
+        return await self._client._arequest("GET", f"customUse/{property_id}", response_type=CustomUse)
+
+    async def revisions(
+        self,
+        property_id: int,
+        current_as_of_start: str | None = None,
+        current_as_of_end: str | None = None,
+    ) -> Response:
+        return await self._client._arequest(
+            "GET",
+            f"customUse/{property_id}/detailRevisions",
+            params={"currentAsOfStart": current_as_of_start, "currentAsOfEnd": current_as_of_end},
+            response_type=Response,
+        )
+
+    async def add_revision(self, property_id: int, data: CustomUse) -> Response:
+        return await self._client._arequest(
+            "POST", f"customUse/{property_id}/details", data=data, response_type=Response
+        )
+
+    async def get_detail(self, detail_id: int) -> CustomUseDetailsType:
+        return cast(
+            CustomUseDetailsType,
+            await self._client._arequest_polymorphic("GET", f"customUse/details/{detail_id}"),
+        )
+
+    async def update_detail(self, detail_id: int, data: CustomUse) -> Response:
+        return await self._client._arequest("PUT", f"customUse/details/{detail_id}", data=data, response_type=Response)
+
+    async def delete_detail(self, detail_id: int) -> Response:
+        return await self._client._arequest("DELETE", f"customUse/details/{detail_id}", response_type=Response)
+
+
+class AsyncPropertyUseResource(AsyncResource):
+    def __init__(self, client: EpaPmAsyncClient) -> None:
+        super().__init__(client)
+        self.use_details = AsyncUseDetailsResource(client)
+        self.custom_use = AsyncCustomUseResource(client)
+
+    async def list(self, property_id: int) -> Response:
+        return await self._client._arequest("GET", f"property/{property_id}/propertyUse/list", response_type=Response)
+
+    async def create(self, property_id: int, data: PropertyUse) -> Response:
+        return await self._client._arequest(
+            "POST", f"property/{property_id}/propertyUse", data=data, response_type=Response
+        )
+
+    async def what_changed(self, customer_id: int, date: str) -> Response:
+        return await self._client._arequest(
+            "GET",
+            f"customer/{customer_id}/propertyUse/whatChanged",
+            params={"date": date},
+            response_type=Response,
+        )
+
+    async def get(self, property_use_id: int) -> PropertyUse:
+        return cast(
+            PropertyUse,
+            await self._client._arequest_polymorphic("GET", f"propertyUse/{property_use_id}"),
+        )
+
+    async def update(self, property_use_id: int, data: PropertyUse) -> Response:
+        return await self._client._arequest("PUT", f"propertyUse/{property_use_id}", data=data, response_type=Response)
+
+    async def delete(self, property_use_id: int) -> Response:
+        return await self._client._arequest("DELETE", f"propertyUse/{property_use_id}", response_type=Response)

epa_pm_api_wrapper/resources/report.py

@@ -0,0 +1,169 @@
+"""Report resource — `/reports` and `/reports/templates` endpoints.
+
+``report.templates`` is a sub-namespace for template management; ``report``
+itself covers the report instances and the metrics catalog.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from epa_pm_api_wrapper.models import (
+    Report,
+    ReportMetrics,
+    ReportStatus,
+    ReportTemplate,
+    Response,
+)
+
+from ._base import AsyncResource, Resource
+
+if TYPE_CHECKING:
+    from epa_pm_api_wrapper.client import EpaPmAsyncClient, EpaPmClient
+
+
+class ReportTemplatesResource(Resource):
+    def list(self, template_type: str | None = None) -> Response:
+        """List report templates available to the authenticated account."""
+        return self._client._request("GET", "reports/templates", params={"type": template_type}, response_type=Response)
+
+    def get(self, template_id: int) -> ReportTemplate:
+        """Get a specific report template."""
+        return self._client._request("GET", f"reports/templates/{template_id}", response_type=ReportTemplate)
+
+    def create(self, template: ReportTemplate) -> Response:
+        """Create a new custom report template."""
+        return self._client._request("POST", "reports/templates", data=template, response_type=Response)
+
+    def update(self, template_id: int, template: ReportTemplate) -> Response:
+        """Update an existing custom report template."""
+        return self._client._request("PUT", f"reports/templates/{template_id}", data=template, response_type=Response)
+
+    def delete(self, template_id: int) -> Response:
+        """Delete a custom report template."""
+        return self._client._request("DELETE", f"reports/templates/{template_id}", response_type=Response)
+
+
+class ReportResource(Resource):
+    def __init__(self, client: EpaPmClient) -> None:
+        super().__init__(client)
+        self.templates = ReportTemplatesResource(client)
+
+    def list(self, report_type: str | None = None) -> Response:
+        """List reports in the authenticated account."""
+        return self._client._request("GET", "reports", params={"type": report_type}, response_type=Response)
+
+    def get(self, report_id: int) -> Report:
+        """Get a specific report."""
+        return self._client._request("GET", f"reports/{report_id}", response_type=Report)
+
+    def update(self, report_id: int, report: Report) -> Response:
+        """Update an existing report."""
+        return self._client._request("PUT", f"reports/{report_id}", data=report, response_type=Response)
+
+    def generate(self, report_id: int) -> Response:
+        """Trigger generation of a report. Poll ``status`` for completion."""
+        return self._client._request("POST", f"reports/{report_id}/generate", response_type=Response)
+
+    def status(self, report_id: int) -> ReportStatus:
+        """Get the generation status of a report."""
+        return self._client._request("GET", f"reports/{report_id}/status", response_type=ReportStatus)
+
+    def download(self, report_id: int, report_format: str = "XML") -> bytes:
+        """Download a generated report's results as raw bytes.
+
+        ``report_format`` is the EPA-defined format string (e.g. ``"XML"``, ``"EXCEL"``).
+        The report must already have been generated successfully; otherwise this raises
+        ``EpaPmApiError``. The caller is responsible for interpreting the bytes
+        according to the requested format.
+        """
+        url = f"{self._client.base_url}/reports/{report_id}/download"
+        resp = self._client.client.request("GET", url, params={"type": report_format})
+        self._client._raise_for_response(resp)
+        return resp.content
+
+    def metrics(
+        self,
+        group_ids: str | None = None,
+        available_to_custom_metrics: bool | None = None,
+    ) -> ReportMetrics:
+        """List metrics available for inclusion in a report template.
+
+        ``group_ids`` is a comma-separated string of metric group IDs to filter by.
+        ``available_to_custom_metrics`` filters to metrics usable in custom metrics.
+        """
+        params = {
+            "groupIds": group_ids,
+            "availableToCustomMetrics": ("true" if available_to_custom_metrics else "false")
+            if available_to_custom_metrics is not None
+            else None,
+        }
+        return self._client._request("GET", "reports/metrics", params=params, response_type=ReportMetrics)
+
+
+class AsyncReportTemplatesResource(AsyncResource):
+    async def list(self, template_type: str | None = None) -> Response:
+        return await self._client._arequest(
+            "GET", "reports/templates", params={"type": template_type}, response_type=Response
+        )
+
+    async def get(self, template_id: int) -> ReportTemplate:
+        return await self._client._arequest("GET", f"reports/templates/{template_id}", response_type=ReportTemplate)
+
+    async def create(self, template: ReportTemplate) -> Response:
+        return await self._client._arequest("POST", "reports/templates", data=template, response_type=Response)
+
+    async def update(self, template_id: int, template: ReportTemplate) -> Response:
+        return await self._client._arequest(
+            "PUT", f"reports/templates/{template_id}", data=template, response_type=Response
+        )
+
+    async def delete(self, template_id: int) -> Response:
+        return await self._client._arequest("DELETE", f"reports/templates/{template_id}", response_type=Response)
+
+
+class AsyncReportResource(AsyncResource):
+    def __init__(self, client: EpaPmAsyncClient) -> None:
+        super().__init__(client)
+        self.templates = AsyncReportTemplatesResource(client)
+
+    async def list(self, report_type: str | None = None) -> Response:
+        return await self._client._arequest("GET", "reports", params={"type": report_type}, response_type=Response)
+
+    async def get(self, report_id: int) -> Report:
+        return await self._client._arequest("GET", f"reports/{report_id}", response_type=Report)
+
+    async def update(self, report_id: int, report: Report) -> Response:
+        return await self._client._arequest("PUT", f"reports/{report_id}", data=report, response_type=Response)
+
+    async def generate(self, report_id: int) -> Response:
+        return await self._client._arequest("POST", f"reports/{report_id}/generate", response_type=Response)
+
+    async def status(self, report_id: int) -> ReportStatus:
+        return await self._client._arequest("GET", f"reports/{report_id}/status", response_type=ReportStatus)
+
+    async def download(self, report_id: int, report_format: str = "XML") -> bytes:
+        """Download a generated report's results as raw bytes.
+
+        ``report_format`` is the EPA-defined format string (e.g. ``"XML"``, ``"EXCEL"``).
+        The report must already have been generated successfully; otherwise this raises
+        ``EpaPmApiError``. The caller is responsible for interpreting the bytes
+        according to the requested format.
+        """
+        url = f"{self._client.base_url}/reports/{report_id}/download"
+        resp = await self._client.client.request("GET", url, params={"type": report_format})
+        self._client._raise_for_response(resp)
+        return resp.content
+
+    async def metrics(
+        self,
+        group_ids: str | None = None,
+        available_to_custom_metrics: bool | None = None,
+    ) -> ReportMetrics:
+        params = {
+            "groupIds": group_ids,
+            "availableToCustomMetrics": ("true" if available_to_custom_metrics else "false")
+            if available_to_custom_metrics is not None
+            else None,
+        }
+        return await self._client._arequest("GET", "reports/metrics", params=params, response_type=ReportMetrics)

epa_pm_api_wrapper/resources/share.py

@@ -0,0 +1,139 @@
+"""Connection / share resource — `/connect`, `/share`, `/disconnect`,
+`/unshare`, `/notification` endpoints.
+
+Pending-list reads list inbound requests waiting for action; the response
+methods (`respond_to_*`) accept or reject a specific pending request by
+posting a ``SharingResponse`` body. Unshare/disconnect tear down existing
+relationships.
+"""
+
+from __future__ import annotations
+
+from epa_pm_api_wrapper.models import (
+    NotificationList,
+    PendingList,
+    Response,
+    SharingResponse,
+    TerminateSharingResponse,
+)
+
+from ._base import AsyncResource, Resource
+
+
+class ShareResource(Resource):
+    # ---- Pending lists ----
+
+    def pending_connections(self) -> PendingList:
+        """List pending customer connection requests."""
+        return self._client._request("GET", "connect/account/pending/list", response_type=PendingList)
+
+    def pending_property_shares(self) -> PendingList:
+        """List pending property share requests from connected customers."""
+        return self._client._request("GET", "share/property/pending/list", response_type=PendingList)
+
+    def pending_meter_shares(self) -> PendingList:
+        """List pending meter share requests from connected customers."""
+        return self._client._request("GET", "share/meter/pending/list", response_type=PendingList)
+
+    # ---- Responses to pending requests ----
+
+    def respond_to_connection(self, account_id: int, response: SharingResponse) -> Response:
+        """Accept or reject a pending connection request from a customer."""
+        return self._client._request("POST", f"connect/account/{account_id}", data=response, response_type=Response)
+
+    def respond_to_property_share(self, property_id: int, response: SharingResponse) -> Response:
+        """Accept or reject a pending property share request."""
+        return self._client._request("POST", f"share/property/{property_id}", data=response, response_type=Response)
+
+    def respond_to_meter_share(self, meter_id: int, response: SharingResponse) -> Response:
+        """Accept or reject a pending meter share request."""
+        return self._client._request("POST", f"share/meter/{meter_id}", data=response, response_type=Response)
+
+    # ---- Tearing down existing relationships ----
+
+    def disconnect(self, account_id: int, keep_shares: bool = False) -> Response:
+        """Terminate an existing connection.
+
+        ``keep_shares=False`` (the default) also removes property and meter shares.
+        """
+        return self._client._request(
+            "POST",
+            f"disconnect/account/{account_id}",
+            params={"keepShares": "true" if keep_shares else "false"},
+            response_type=Response,
+        )
+
+    def unshare_property(self, property_id: int, response: TerminateSharingResponse) -> Response:
+        """Remove an existing property share. Associated meter shares are also removed."""
+        return self._client._request(
+            "POST",
+            f"unshare/property/{property_id}",
+            data=response,
+            response_type=Response,
+        )
+
+    def unshare_meter(self, meter_id: int, response: TerminateSharingResponse) -> Response:
+        """Remove an existing meter share."""
+        return self._client._request("POST", f"unshare/meter/{meter_id}", data=response, response_type=Response)
+
+    # ---- Notifications about disconnect/unshare events ----
+
+    def notifications(self, clear: bool = False) -> NotificationList:
+        """List notifications for disconnect/unshare events.
+
+        Pass ``clear=True`` to mark them as read after retrieval.
+        """
+        return self._client._request(
+            "GET",
+            "notification/list",
+            params={"clear": "true" if clear else "false"},
+            response_type=NotificationList,
+        )
+
+
+class AsyncShareResource(AsyncResource):
+    async def pending_connections(self) -> PendingList:
+        return await self._client._arequest("GET", "connect/account/pending/list", response_type=PendingList)
+
+    async def pending_property_shares(self) -> PendingList:
+        return await self._client._arequest("GET", "share/property/pending/list", response_type=PendingList)
+
+    async def pending_meter_shares(self) -> PendingList:
+        return await self._client._arequest("GET", "share/meter/pending/list", response_type=PendingList)
+
+    async def respond_to_connection(self, account_id: int, response: SharingResponse) -> Response:
+        return await self._client._arequest(
+            "POST", f"connect/account/{account_id}", data=response, response_type=Response
+        )
+
+    async def respond_to_property_share(self, property_id: int, response: SharingResponse) -> Response:
+        return await self._client._arequest(
+            "POST", f"share/property/{property_id}", data=response, response_type=Response
+        )
+
+    async def respond_to_meter_share(self, meter_id: int, response: SharingResponse) -> Response:
+        return await self._client._arequest("POST", f"share/meter/{meter_id}", data=response, response_type=Response)
+
+    async def disconnect(self, account_id: int, keep_shares: bool = False) -> Response:
+        return await self._client._arequest(
+            "POST",
+            f"disconnect/account/{account_id}",
+            params={"keepShares": "true" if keep_shares else "false"},
+            response_type=Response,
+        )
+
+    async def unshare_property(self, property_id: int, response: TerminateSharingResponse) -> Response:
+        return await self._client._arequest(
+            "POST", f"unshare/property/{property_id}", data=response, response_type=Response
+        )
+
+    async def unshare_meter(self, meter_id: int, response: TerminateSharingResponse) -> Response:
+        return await self._client._arequest("POST", f"unshare/meter/{meter_id}", data=response, response_type=Response)
+
+    async def notifications(self, clear: bool = False) -> NotificationList:
+        return await self._client._arequest(
+            "GET",
+            "notification/list",
+            params={"clear": "true" if clear else "false"},
+            response_type=NotificationList,
+        )

epa_pm_api_wrapper/resources/target_finder.py

@@ -0,0 +1,34 @@
+"""Target Finder resource — `/targetFinder` endpoint.
+
+Estimates annual energy metrics from a property design. Single endpoint:
+``POST /targetFinder?measurementSystem={EPA|EU}``.
+"""
+
+from __future__ import annotations
+
+from epa_pm_api_wrapper.models import PropertyMetrics, TargetFinder
+
+from ._base import AsyncResource, Resource
+
+
+class TargetFinderResource(Resource):
+    def evaluate(self, design: TargetFinder, measurement_system: str = "EPA") -> PropertyMetrics:
+        """Run Target Finder against a candidate design and return the resulting metrics."""
+        return self._client._request(
+            "POST",
+            "targetFinder",
+            data=design,
+            params={"measurementSystem": measurement_system},
+            response_type=PropertyMetrics,
+        )
+
+
+class AsyncTargetFinderResource(AsyncResource):
+    async def evaluate(self, design: TargetFinder, measurement_system: str = "EPA") -> PropertyMetrics:
+        return await self._client._arequest(
+            "POST",
+            "targetFinder",
+            data=design,
+            params={"measurementSystem": measurement_system},
+            response_type=PropertyMetrics,
+        )