EPA-PM-API-Wrapper 0.4.0__tar.gz → 0.5.0__tar.gz

epa_pm_api_wrapper-0.5.0/CHANGELOG/0.5.0.md

@@ -0,0 +1,25 @@
+# 0.5.0 (2026-05-07)
+
+### Added
+
+- **`client.metrics.blockers(property_id, year, month)`** — convenience aggregator over the two `reasonsFor*` endpoints. Returns a `PropertyBlockers` with the alerts grouped into `.energy` (from `reasonsForNoScore`) and `.water` (from `reasonsForNoWaterScore`) lists. The aggregate is truthy iff at least one blocker is present, so the common "is this property unblocked?" check reads naturally as `if blockers: ...`. The async variant fans the two requests out concurrently via `asyncio.gather`; the sync variant issues them sequentially.
+- **`PropertyBlockers`** dataclass, exported from the top-level package, carrying `property_id`, `year`, `month`, and the `energy` / `water` alert lists (each a list of `AlertsTypeAlert` with `name` + `description`).
+
+### Caller impact
+
+- Purely additive. Existing `reasons_for_no_score` / `reasons_for_no_water_score` callers are unaffected — `blockers()` is a thin wrapper, not a replacement.
+
+  ```python
+  blockers = client.metrics.blockers(prop_id, 2025, 12)
+  if blockers:
+      for a in blockers.energy:
+          print("energy:", a.name, "—", a.description)
+      for a in blockers.water:
+          print("water:", a.name, "—", a.description)
+  ```
+
+  Async is identical (`await client.metrics.blockers(...)` → `PropertyBlockers`).
+
+### Contributors
+
+[@harryw1](https://github.com/harryw1) (Harrison Weiss)

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EPA-PM-API-Wrapper
-Version: 0.4.0
+Version: 0.5.0
 Summary: Client wrapper for the EPA Portfolio Manager API.
 Project-URL: bugs, https://github.com/harryw1/EPA-PM-API-Wrapper/issues
 Project-URL: changelog, https://github.com/harryw1/EPA-PM-API-Wrapper/releases

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/docs/api.md

@@ -10,16 +10,24 @@ coroutines.
 ## Clients
 
 ::: epa_pm_api_wrapper.client.EpaPmClient
+    options:
+      heading_level: 3
 
 ::: epa_pm_api_wrapper.client.EpaPmAsyncClient
+    options:
+      heading_level: 3
 
 ## Exceptions
 
 ::: epa_pm_api_wrapper.exceptions
+    options:
+      heading_level: 3
 
 ## Retry configuration
 
 ::: epa_pm_api_wrapper.retry.RetryConfig
+    options:
+      heading_level: 3
 
 ## Resources
 

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/docs/metrics.md

@@ -377,9 +377,30 @@ use type, or out-of-range values for some use detail.
 ```python
 alerts = client.metrics.reasons_for_no_score(prop_id, 2025, 12)
 for a in alerts.alert or []:
-    print(a.message)
+    print(a.name, "—", a.description)
 ```
 
+### `client.metrics.blockers(property_id, year, month)`
+
+Convenience aggregator that calls both `reasonsFor*` endpoints and returns
+a `PropertyBlockers` with the alerts grouped by score type. The async client
+fans the two requests out concurrently via `asyncio.gather`; the sync client
+issues them sequentially. The result is truthy iff at least one blocker is
+present, so the common "is this property unblocked?" check reads naturally:
+
+```python
+blockers = client.metrics.blockers(prop_id, 2025, 12)
+if blockers:
+    for a in blockers.energy:
+        print("energy:", a.name, "—", a.description)
+    for a in blockers.water:
+        print("water:", a.name, "—", a.description)
+```
+
+`PropertyBlockers` is exported at the top level (`from epa_pm_api_wrapper
+import PropertyBlockers`) for type annotations; it carries `property_id`,
+`year`, `month`, and the `energy` / `water` alert lists.
+
 ## See also
 
 - [API reference](api.md) — auto-generated signatures and per-method

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "EPA-PM-API-Wrapper"
-version = "0.4.0"
+version = "0.5.0"
 description = "Client wrapper for the EPA Portfolio Manager API."
 readme = "README.md"
 authors = [

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/src/epa_pm_api_wrapper/__init__.py

@@ -14,6 +14,7 @@ from epa_pm_api_wrapper.models import (
     MeterData,
     SharingResponse,
 )
+from epa_pm_api_wrapper.resources.metrics import PropertyBlockers
 from epa_pm_api_wrapper.resources.report import DownloadResult
 from epa_pm_api_wrapper.retry import RetryConfig
 
@@ -28,6 +29,7 @@ __all__ = [
     "EpaPmError",
     "MeterConsumption",
     "MeterData",
+    "PropertyBlockers",
     "RetryConfig",
     "SharingResponse",
     "link_id",

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/src/epa_pm_api_wrapper/models/report.py

@@ -17,7 +17,11 @@ class Report:
     :ivar template_id: The id of the template.
     :ivar template_name: The name of the template.
     :ivar properties: The list of properties that the report will be run
-        for.
+        for. EPA does **not** treat an empty or missing ``properties`` as
+        "all properties on the account" — generating such a report
+        succeeds but produces ``<numberOfProperties>0</numberOfProperties>``
+        and no per-property data. Populate ``properties.id`` explicitly
+        before calling ``report.generate()``.
     :ivar report_generation_status: The current generation status of the
         report.
     """

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/src/epa_pm_api_wrapper/models/report_properties.py

@@ -6,7 +6,10 @@ from dataclasses import dataclass, field
 @dataclass(kw_only=True)
 class ReportProperties:
     """
-    :ivar id: The unique identifier for each property.
+    :ivar id: The list of property IDs the report will be run against.
+        Must be populated before generating the report — EPA does not
+        infer "all properties on the account" from an empty list and will
+        produce a report with zero properties in scope.
     """
 
     class Meta:

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/src/epa_pm_api_wrapper/resources/metrics.py

@@ -21,7 +21,11 @@ Canonical EPA reference: https://portfoliomanager.energystar.gov/webservices/hom
 
 from __future__ import annotations
 
+import asyncio
+from dataclasses import dataclass, field
+
 from epa_pm_api_wrapper.models import Alerts, PropertyMetrics
+from epa_pm_api_wrapper.models.alerts_type_alert import AlertsTypeAlert
 
 from ._base import AsyncResource, Resource
 
@@ -30,6 +34,47 @@ def _metric_header(metrics: list[str] | str) -> str:
     return metrics if isinstance(metrics, str) else ",".join(metrics)
 
 
+@dataclass
+class PropertyBlockers:
+    """Aggregate of the two ``reasonsFor*`` endpoints for one property/period.
+
+    ``energy`` carries the alerts EPA returns for ``reasonsForNoScore`` (the
+    ENERGY STAR Score blockers); ``water`` carries the alerts for
+    ``reasonsForNoWaterScore`` (the multifamily-only water score blockers).
+    Each list contains the underlying :class:`AlertsTypeAlert` values
+    (``name`` + ``description``) exactly as EPA returned them.
+
+    Truthiness reflects whether *any* blocker is present, so the common
+    "is this property unblocked?" check reads naturally::
+
+        blockers = client.metrics.blockers(prop_id, 2025, 12)
+        if blockers:
+            for alert in blockers.energy:
+                print("energy:", alert.name, "—", alert.description)
+            for alert in blockers.water:
+                print("water:", alert.name, "—", alert.description)
+    """
+
+    property_id: int | None = None
+    year: int | None = None
+    month: int | None = None
+    energy: list[AlertsTypeAlert] = field(default_factory=list)
+    water: list[AlertsTypeAlert] = field(default_factory=list)
+
+    def __bool__(self) -> bool:
+        return bool(self.energy) or bool(self.water)
+
+
+def _merge_blockers(property_id: int, year: int, month: int, energy: Alerts, water: Alerts) -> PropertyBlockers:
+    return PropertyBlockers(
+        property_id=property_id,
+        year=year,
+        month=month,
+        energy=list(energy.alert),
+        water=list(water.alert),
+    )
+
+
 class MetricsResource(Resource):
     def get(
         self,
@@ -181,6 +226,21 @@ class MetricsResource(Resource):
             response_type=Alerts,
         )
 
+    def blockers(self, property_id: int, year: int, month: int) -> PropertyBlockers:
+        """Aggregate the EPA-side reasons a property has no ENERGY STAR score.
+
+        Calls both ``reasonsForNoScore`` (energy) and ``reasonsForNoWaterScore``
+        (water, multifamily-only) and returns a :class:`PropertyBlockers` with
+        the alerts grouped by score type. The result is truthy iff at least
+        one blocker is present, so a property with everything in order returns
+        a falsy aggregate. Both calls are issued sequentially in the sync
+        client; use the async client's :meth:`AsyncMetricsResource.blockers`
+        for concurrent fan-out.
+        """
+        energy = self.reasons_for_no_score(property_id, year, month)
+        water = self.reasons_for_no_water_score(property_id, year, month)
+        return _merge_blockers(property_id, year, month, energy, water)
+
 
 class AsyncMetricsResource(AsyncResource):
     async def get(
@@ -330,3 +390,16 @@ class AsyncMetricsResource(AsyncResource):
             params={"year": year, "month": month},
             response_type=Alerts,
         )
+
+    async def blockers(self, property_id: int, year: int, month: int) -> PropertyBlockers:
+        """Concurrently aggregate the EPA-side reasons a property has no ENERGY STAR score.
+
+        Async counterpart of :meth:`MetricsResource.blockers` — fans out the
+        two ``reasonsFor*`` calls via :func:`asyncio.gather` and returns a
+        :class:`PropertyBlockers` with the alerts grouped by score type.
+        """
+        energy, water = await asyncio.gather(
+            self.reasons_for_no_score(property_id, year, month),
+            self.reasons_for_no_water_score(property_id, year, month),
+        )
+        return _merge_blockers(property_id, year, month, energy, water)

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/tests/test_async_client.py

@@ -155,6 +155,40 @@ async def test_pm_metrics_header_propagates_through_async():
     assert request.url.params.get("measurementSystem") == "EPA"
 
 
+@respx.mock
+async def test_metrics_blockers_aggregates_concurrently():
+    energy_xml = """<?xml version="1.0"?>
+<alerts year="2025" month="12" propertyId="19939329">
+    <alert>
+        <name>Missing meter data</name>
+        <description>No active meter</description>
+    </alert>
+</alerts>"""
+    water_xml = """<?xml version="1.0"?>
+<alerts year="2025" month="12" propertyId="19939329">
+    <alert>
+        <name>Unsupported property type</name>
+        <description>Water score is multifamily-only</description>
+    </alert>
+</alerts>"""
+
+    energy_route = respx.get(f"{BASE}/property/19939329/reasonsForNoScore").mock(
+        return_value=httpx.Response(200, content=energy_xml)
+    )
+    water_route = respx.get(f"{BASE}/property/19939329/reasonsForNoWaterScore").mock(
+        return_value=httpx.Response(200, content=water_xml)
+    )
+
+    async with EpaPmAsyncClient("user", "pass") as client:
+        blockers = await client.metrics.blockers(19939329, year=2025, month=12)
+
+    assert energy_route.call_count == 1
+    assert water_route.call_count == 1
+    assert blockers
+    assert [a.name for a in blockers.energy] == ["Missing meter data"]
+    assert [a.name for a in blockers.water] == ["Unsupported property type"]
+
+
 @respx.mock
 async def test_polymorphic_get_through_async():
     use_xml = """<?xml version="1.0"?>

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/tests/test_client.py

@@ -906,6 +906,73 @@ def test_get_reasons_for_no_score():
     assert len(alerts.alert) == 1
 
 
+@respx.mock
+def test_metrics_blockers_aggregates_both_endpoints():
+    energy_xml = """<?xml version="1.0" encoding="UTF-8"?>
+<alerts year="2025" month="12" propertyId="19939329">
+    <alert>
+        <name>Missing meter data</name>
+        <description>No active meter</description>
+    </alert>
+    <alert>
+        <name>Insufficient history</name>
+        <description>Less than 12 months of data</description>
+    </alert>
+</alerts>"""
+    water_xml = """<?xml version="1.0" encoding="UTF-8"?>
+<alerts year="2025" month="12" propertyId="19939329">
+    <alert>
+        <name>Unsupported property type</name>
+        <description>Water score is multifamily-only</description>
+    </alert>
+</alerts>"""
+
+    energy_route = respx.get(f"{BASE}/property/19939329/reasonsForNoScore").mock(
+        return_value=httpx.Response(200, content=energy_xml)
+    )
+    water_route = respx.get(f"{BASE}/property/19939329/reasonsForNoWaterScore").mock(
+        return_value=httpx.Response(200, content=water_xml)
+    )
+
+    client = EpaPmClient("user", "pass")
+    blockers = client.metrics.blockers(19939329, year=2025, month=12)
+
+    assert energy_route.call_count == 1
+    assert water_route.call_count == 1
+    assert blockers  # truthy when any blockers exist
+    assert blockers.property_id == 19939329
+    assert blockers.year == 2025
+    assert blockers.month == 12
+
+    assert [a.name for a in blockers.energy] == ["Missing meter data", "Insufficient history"]
+    assert blockers.energy[0].description == "No active meter"
+    assert [a.name for a in blockers.water] == ["Unsupported property type"]
+
+    # Year/month are forwarded as query params on both calls.
+    for route in (energy_route, water_route):
+        request = route.calls[0].request
+        assert request.url.params.get("year") == "2025"
+        assert request.url.params.get("month") == "12"
+
+
+@respx.mock
+def test_metrics_blockers_empty_is_falsy():
+    empty_xml = """<?xml version="1.0" encoding="UTF-8"?>
+<alerts year="2025" month="12" propertyId="19939329"/>"""
+
+    respx.get(f"{BASE}/property/19939329/reasonsForNoScore").mock(return_value=httpx.Response(200, content=empty_xml))
+    respx.get(f"{BASE}/property/19939329/reasonsForNoWaterScore").mock(
+        return_value=httpx.Response(200, content=empty_xml)
+    )
+
+    client = EpaPmClient("user", "pass")
+    blockers = client.metrics.blockers(19939329, year=2025, month=12)
+
+    assert not blockers
+    assert blockers.energy == []
+    assert blockers.water == []
+
+
 def test_client_urls():
     # Live environment (default)
     client = EpaPmClient("user", "pass")

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/uv.lock

@@ -149,7 +149,7 @@ wheels = [
 
 [[package]]
 name = "epa-pm-api-wrapper"
-version = "0.4.0"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

{epa_pm_api_wrapper-0.4.0 → epa_pm_api_wrapper-0.5.0}/zensical.toml

@@ -28,3 +28,6 @@ toggle.name = "Switch to light mode"
 
 [project.plugins.mkdocstrings.handlers.python]
 paths = ["src"]
+
+[project.plugins.mkdocstrings.handlers.python.options]
+heading_level = 4