EPA-PM-API-Wrapper 0.3.3__tar.gz → 0.3.5__tar.gz

epa_pm_api_wrapper-0.3.5/CHANGELOG/0.3.4.md

@@ -0,0 +1,13 @@
+# 0.3.4 (2026-05-07)
+
+### Fixed
+
+- **`property_use.use_details.revisions()`** declared `response_type=Response`, but the EPA returns a `<useDetails>` envelope (not `<response>`) whose children are the concrete use-detail subtypes (`<totalGrossFloorArea>`, `<numberOfComputers>`, `<weeklyOperatingHours>`, …). xsdata's strict parser raised `ParserError: Unknown property response:totalGrossFloorArea` on every call, so callers could not paginate use-detail history at all. The method now declares `response_type=UseDetails` (the existing 122-field dataclass already covers every subtype) and returns it directly. Sync + async kept symmetric.
+
+### Caller impact
+
+- `revisions()` now returns a typed `UseDetails` instead of `Response`. Callers that branched on `Response.status` (which never returned successfully anyway) should switch to reading the typed lists, e.g. `result.total_gross_floor_area`, `result.number_of_computers`, etc. Symmetric with `add_revision()` which already takes a `UseDetails`.
+
+### Contributors
+
+[@harryw1](https://github.com/harryw1) (Harrison Weiss)

epa_pm_api_wrapper-0.3.5/CHANGELOG/0.3.5.md

@@ -0,0 +1,13 @@
+# 0.3.5 (2026-05-07)
+
+### Fixed
+
+- **`Building.number_of_buildings`** — the EPA XSD declares `<building type="propertyType"/>`, so the auto-generated `Building` dataclass inherited the full `PropertyType` field set including `numberOfBuildings`. The EPA's runtime validator disagrees with their own schema and rejects `<building>` bodies that include the element with HTTP 400 (`-100: unexpected element … numberOfBuildings`). The field is now overridden on `Building` with `init=False`, `default=None`, and `metadata={"type": "Ignore"}`: the constructor refuses the kwarg loudly (`TypeError`) instead of silently producing a body the EPA rejects, and the serializer drops the element from the wire.
+
+### Caller impact
+
+- **Breaking (signature only — runtime never worked):** `Building(number_of_buildings=...)` now raises `TypeError` instead of round-tripping out to a 400 from the EPA. No legitimate caller could have used the field successfully.
+
+### Contributors
+
+[@harryw1](https://github.com/harryw1) (Harrison Weiss)

{epa_pm_api_wrapper-0.3.3 → epa_pm_api_wrapper-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EPA-PM-API-Wrapper
-Version: 0.3.3
+Version: 0.3.5
 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.3.3 → epa_pm_api_wrapper-0.3.5}/docs/usage.md

@@ -300,6 +300,51 @@ print(use.name)            # PropertyUse base attributes still apply
 The declared return type is the abstract base (`PropertyUse`); the runtime
 type is the concrete subtype.
 
+### Bulk-import waste data
+
+`waste_data.add()` requires the request body wrapped in a `WasteDataList`
+(matching the EPA's wire format), not a bare record — even for one entry.
+The response echoes the created records with server-assigned IDs:
+
+```python
+from epa_pm_api_wrapper import EpaPmClient
+from epa_pm_api_wrapper.models import WasteData, WasteDataList
+from xsdata.models.datatype import XmlDate
+from decimal import Decimal
+
+with EpaPmClient(username, password) as client:
+    payload = WasteDataList(
+        waste_data=[
+            WasteData(
+                start_date=XmlDate(2024, 1, 1),
+                end_date=XmlDate(2024, 1, 31),
+                quantity=Decimal("125.5"),
+            ),
+            # …more records up to 120 per call…
+        ],
+    )
+    created = client.waste_data.add(meter_id, payload)
+    for record in created.waste_data or []:
+        print(record.id, record.start_date, record.quantity)
+```
+
+### Energy meters vs. waste meters
+
+`GET /meter/{id}` returns either `<meter>` (energy, water, etc.) or
+`<wasteMeter>` (trash, recycling, …) depending on the meter type, with
+disjoint child schemas. `meter.get()` returns `Meter | WasteMeter` and
+auto-resolves to the matching dataclass; disambiguate with `isinstance`:
+
+```python
+from epa_pm_api_wrapper.models import WasteMeter
+
+m = client.meter.get(meter_id)
+if isinstance(m, WasteMeter):
+    print(m.data_entry_method, m.container_size)
+else:
+    print(m.type_value, m.unit_of_measure, m.metered)
+```
+
 ## Going deeper
 
 Every endpoint in the EPA Portfolio Manager web services API is bound to

{epa_pm_api_wrapper-0.3.3 → epa_pm_api_wrapper-0.3.5}/pyproject.toml

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

epa_pm_api_wrapper-0.3.5/scripts/sample_fixture.py

@@ -0,0 +1,299 @@
+"""Create + populate + tear down sample properties on the EPA wstest environment.
+
+Usage:
+    uv run scripts/sample_fixture.py create [--country US] [--count 1] [--populate]
+    uv run scripts/sample_fixture.py populate <property_id>
+    uv run scripts/sample_fixture.py delete <property_id> [<property_id> ...]
+
+`create` calls the EPA's server-side ``/createSampleProperties`` endpoint and
+prints the new property IDs. With ``--populate``, each created property is then
+augmented with extra resources (meters, consumption data, an energy-performance
+project, an additional identifier) so a downstream test can exercise more of
+the API surface than the EPA samples ship with by default.
+
+`populate` skips the create step and adds the same extras to an existing
+property — handy for re-running tests against a known property without
+spawning new ones.
+
+`delete` removes the listed properties via DELETE /property/{id}.
+
+Always targets the test environment. Reads ``EPA_PM_USERNAME`` /
+``EPA_PM_PASSWORD`` from the shell or a project-root ``.env``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from decimal import Decimal
+
+from dotenv import load_dotenv
+from xsdata.models.datatype import XmlDate
+
+from epa_pm_api_wrapper import EpaPmApiError, EpaPmClient, MeterConsumption, MeterData
+from epa_pm_api_wrapper.models import (
+    AdditionalIdentifier,
+    EnergyPerformanceProject,
+    Meter,
+    MeterTypeUnitOfMeasure,
+    TypeOfMeter,
+)
+
+
+@dataclass
+class PopulateReport:
+    """Summary of resources added to one property by ``populate()``.
+
+    Recorded so callers can correlate created IDs with what they sent (and so
+    failures partway through don't lose the IDs that did succeed).
+    """
+
+    property_id: int
+    meter_ids: list[int] = field(default_factory=list)
+    consumption_ids: list[int] = field(default_factory=list)
+    epp_id: int | None = None
+    identifier_id: int | None = None
+    failures: list[str] = field(default_factory=list)
+
+
+def _required_env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        print(f"missing required env var {name} — set it or populate .env")
+        sys.exit(2)
+    return value
+
+
+def _build_client() -> EpaPmClient:
+    load_dotenv(override=True)
+    username = _required_env("EPA_PM_USERNAME")
+    password = _required_env("EPA_PM_PASSWORD")
+    return EpaPmClient(username=username, password=password, use_test_env=True)
+
+
+def _consumption_records(months: int = 3) -> list[MeterConsumption]:
+    """Build ``months`` of monthly consumption records starting Jan of last year.
+
+    Uses fixed-but-non-round values so test assertions can spot rounding /
+    precision issues without writing ad-hoc fixtures.
+    """
+    base_year = datetime.now(UTC).year - 1
+    records: list[MeterConsumption] = []
+    for i in range(months):
+        month = i + 1
+        # Dec edge handled by month=12 logic; we only go up to 12 months.
+        end_day = 28 if month == 2 else 30
+        records.append(
+            MeterConsumption(
+                start_date=XmlDate(base_year, month, 1),
+                end_date=XmlDate(base_year, month, end_day),
+                usage=Decimal(f"{1000 + i * 250}.{42 + i}"),
+                cost=Decimal(f"{120 + i * 30}.5{i}"),
+                estimated_value=False,
+            )
+        )
+    return records
+
+
+def _add_meter_with_consumption(
+    client: EpaPmClient,
+    property_id: int,
+    name: str,
+    meter_type: TypeOfMeter,
+    unit: MeterTypeUnitOfMeasure,
+    report: PopulateReport,
+) -> None:
+    """Create one meter and seed it with a few months of consumption.
+
+    Failures are recorded on ``report`` rather than raised so a single bad
+    sub-step doesn't take down the whole populate run.
+    """
+    try:
+        create_resp = client.meter.create(
+            property_id,
+            Meter(
+                type_value=meter_type,
+                name=name,
+                metered=True,
+                unit_of_measure=unit,
+                first_bill_date=XmlDate(datetime.now(UTC).year - 1, 1, 1),
+                in_use=True,
+            ),
+        )
+        meter_id = create_resp.id
+        if meter_id is None:
+            report.failures.append(f"meter '{name}': create returned no id")
+            return
+        report.meter_ids.append(meter_id)
+        print(f"    + meter '{name}' id={meter_id}")
+    except EpaPmApiError as exc:
+        report.failures.append(f"meter '{name}': create failed — {exc}")
+        return
+
+    try:
+        added = client.consumption_data.add(meter_id, MeterData(meter_consumption=_consumption_records(months=3)))
+        ids = [r.id for r in (added.meter_consumption or []) if r.id is not None]
+        report.consumption_ids.extend(ids)
+        print(f"      + {len(ids)} consumption record(s)")
+    except EpaPmApiError as exc:
+        report.failures.append(f"meter {meter_id}: consumption add failed — {exc}")
+
+
+def _add_energy_performance_project(client: EpaPmClient, property_id: int, report: PopulateReport) -> None:
+    try:
+        resp = client.property.energy_performance_project.create(
+            property_id,
+            EnergyPerformanceProject(
+                project_name=f"Sample EPP {datetime.now(UTC).strftime('%Y%m%dT%H%M%S')}",
+                project_description="Auto-generated by scripts/sample_fixture.py",
+                implementation_date=XmlDate(datetime.now(UTC).year - 1, 6, 1),
+            ),
+        )
+        report.epp_id = resp.id
+        print(f"    + energy performance project id={resp.id}")
+    except EpaPmApiError as exc:
+        report.failures.append(f"epp create failed — {exc}")
+
+
+def _add_identifier(client: EpaPmClient, property_id: int, report: PopulateReport) -> None:
+    """Add an additional identifier, picking a valid type from the catalog."""
+    try:
+        catalog = client.identifier.types()
+    except EpaPmApiError as exc:
+        report.failures.append(f"identifier types lookup failed — {exc}")
+        return
+
+    types = catalog.additional_identifier_type or []
+    if not types:
+        report.failures.append("identifier types catalog returned no entries")
+        return
+    chosen = types[0]
+
+    try:
+        resp = client.identifier.add(
+            property_id,
+            AdditionalIdentifier(
+                additional_identifier_type=chosen,
+                value=f"sample-{datetime.now(UTC).strftime('%Y%m%dT%H%M%S')}",
+            ),
+        )
+        report.identifier_id = resp.id
+        print(f"    + additional identifier id={resp.id} (type={chosen.name or chosen.id})")
+    except EpaPmApiError as exc:
+        report.failures.append(f"identifier add failed — {exc}")
+
+
+def populate(client: EpaPmClient, property_id: int) -> PopulateReport:
+    """Add a curated set of extra resources to ``property_id``.
+
+    Each step is independent — failures are collected on the returned report
+    rather than aborting the run. Designed to exercise the resource methods
+    that round-trip-test the most error-prone parts of the wire format
+    (meter create, consumption add, polymorphic identifier types, EPP).
+    """
+    report = PopulateReport(property_id=property_id)
+    print(f"  populating property {property_id}")
+    _add_meter_with_consumption(
+        client,
+        property_id,
+        name="Sample Electric",
+        meter_type=TypeOfMeter.ELECTRIC,
+        unit=MeterTypeUnitOfMeasure.K_WH_THOUSAND_WATT_HOURS,
+        report=report,
+    )
+    _add_meter_with_consumption(
+        client,
+        property_id,
+        name="Sample Natural Gas",
+        meter_type=TypeOfMeter.NATURAL_GAS,
+        unit=MeterTypeUnitOfMeasure.THERMS,
+        report=report,
+    )
+    _add_energy_performance_project(client, property_id, report)
+    _add_identifier(client, property_id, report)
+    return report
+
+
+def cmd_create(args: argparse.Namespace) -> int:
+    with _build_client() as client:
+        try:
+            response = client.property.create_samples(country_code=args.country, create_count=args.count)
+        except EpaPmApiError as exc:
+            print(f"FAIL — create_samples raised: {exc}")
+            return 1
+
+        links = (response.links.link if response.links else None) or []
+        if not links:
+            print("FAIL — create_samples returned no property links")
+            return 1
+
+        property_ids = [link.id for link in links if link.id is not None]
+        print(f"Created {len(property_ids)} sample property(ies):")
+        for pid in property_ids:
+            print(f"  - {pid}")
+
+        if args.populate:
+            for pid in property_ids:
+                report = populate(client, pid)
+                if report.failures:
+                    print(f"  ⚠ {len(report.failures)} step(s) failed on {pid}:")
+                    for failure in report.failures:
+                        print(f"    - {failure}")
+        return 0
+
+
+def cmd_populate(args: argparse.Namespace) -> int:
+    with _build_client() as client:
+        report = populate(client, args.property_id)
+        if report.failures:
+            print(f"⚠ {len(report.failures)} step(s) failed:")
+            for failure in report.failures:
+                print(f"  - {failure}")
+            return 1
+    return 0
+
+
+def cmd_delete(args: argparse.Namespace) -> int:
+    failures: list[tuple[int, str]] = []
+    with _build_client() as client:
+        for pid in args.property_ids:
+            try:
+                client.property.delete(pid)
+                print(f"  deleted property {pid}")
+            except EpaPmApiError as exc:
+                failures.append((pid, str(exc)))
+                print(f"  ⚠ failed to delete {pid}: {exc}")
+    if failures:
+        print(f"\nFAIL — {len(failures)} of {len(args.property_ids)} delete(s) failed")
+        return 1
+    print(f"\nOK — deleted {len(args.property_ids)} property(ies)")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Sample-property fixture builder for wstest.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_create = sub.add_parser("create", help="Create sample properties (and optionally populate them).")
+    p_create.add_argument("--country", default="US", help="ISO country code (default: US)")
+    p_create.add_argument("--count", type=int, default=1, help="Number of properties to spawn (default: 1)")
+    p_create.add_argument("--populate", action="store_true", help="Populate each created property with extras")
+    p_create.set_defaults(func=cmd_create)
+
+    p_pop = sub.add_parser("populate", help="Add extras to an existing property.")
+    p_pop.add_argument("property_id", type=int)
+    p_pop.set_defaults(func=cmd_populate)
+
+    p_del = sub.add_parser("delete", help="Delete properties by ID.")
+    p_del.add_argument("property_ids", type=int, nargs="+")
+    p_del.set_defaults(func=cmd_delete)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

epa_pm_api_wrapper-0.3.5/src/epa_pm_api_wrapper/models/building.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .property_type import PropertyType
+
+
+@dataclass(kw_only=True)
+class Building(PropertyType):
+    class Meta:
+        name = "building"
+
+    # `numberOfBuildings` is inherited from PropertyType because the XSD
+    # declares <building> as `propertyType` — but the EPA's runtime rejects
+    # the element on a <building> with HTTP 400 ("unexpected element ...
+    # numberOfBuildings"). Suppress it so the field can't reach the wire,
+    # and remove it from __init__ so callers who try to set it fail loudly
+    # instead of getting an opaque 400. `default=None` keeps response
+    # parsing tolerant in case a future EPA release ever does include it.
+    number_of_buildings: None | int = field(
+        default=None,
+        init=False,
+        metadata={"type": "Ignore"},
+    )

{epa_pm_api_wrapper-0.3.3 → epa_pm_api_wrapper-0.3.5}/src/epa_pm_api_wrapper/resources/property_use.py

@@ -45,13 +45,19 @@ class UseDetailsResource(Resource):
         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."""
+    ) -> UseDetails:
+        """List historical revisions of use details for a property use within a date window.
+
+        The EPA returns a ``<useDetails>`` envelope (not ``<response>``)
+        whose children are the concrete use-detail subtypes
+        (``<totalGrossFloorArea>``, ``<weeklyOperatingHours>``, …). Each
+        is exposed as a typed list on the returned :class:`UseDetails`.
+        """
         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,
+            response_type=UseDetails,
         )
 
     def get(self, use_details_id: int) -> UseAttributeBase:
@@ -181,12 +187,12 @@ class AsyncUseDetailsResource(AsyncResource):
         property_use_id: int,
         current_as_of_start: str | None = None,
         current_as_of_end: str | None = None,
-    ) -> Response:
+    ) -> UseDetails:
         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,
+            response_type=UseDetails,
         )
 
     async def get(self, use_details_id: int) -> UseAttributeBase:

{epa_pm_api_wrapper-0.3.3 → epa_pm_api_wrapper-0.3.5}/tests/test_resources/test_building_and_hierarchy_extras.py

@@ -1,14 +1,48 @@
 """Tests for newly added building.delete plus hierarchy useDetails / wasteData lookups."""
 
 import httpx
+import pytest
 import respx
 
 from epa_pm_api_wrapper.client import EpaPmClient
-from epa_pm_api_wrapper.models import StatusType
+from epa_pm_api_wrapper.models import Building, StatusType
 
 BASE = EpaPmClient.LIVE_BASE_URL
 
 
+def test_building_does_not_serialize_number_of_buildings():
+    """Regression: <building> inherits numberOfBuildings from propertyType in
+    the XSD, but the EPA's runtime rejects it with HTTP 400. Building must
+    drop the field on serialization and refuse to accept it via __init__.
+    """
+    from xsdata.formats.dataclass.serializers import XmlSerializer
+    from xsdata.formats.dataclass.serializers.config import SerializerConfig
+
+    from epa_pm_api_wrapper.models import OccupancyType
+
+    serializer = XmlSerializer(config=SerializerConfig(indent="  "))
+    building = Building(
+        name="test",
+        is_federal_property=False,
+        occupancy_percentage=OccupancyType.VALUE_100,
+    )
+    xml = serializer.render(building)
+    assert "numberOfBuildings" not in xml
+
+    # Call dynamically (typing.cast) so the static type checker doesn't
+    # pre-flag the dropped parameter — we want the runtime TypeError.
+    from typing import Any, cast
+
+    builder = cast(Any, Building)
+    with pytest.raises(TypeError):
+        builder(
+            name="test",
+            is_federal_property=False,
+            occupancy_percentage=OccupancyType.VALUE_100,
+            number_of_buildings=5,
+        )
+
+
 @respx.mock
 def test_delete_building():
     response_xml = """<?xml version="1.0"?><response status="Ok"/>"""

{epa_pm_api_wrapper-0.3.3 → epa_pm_api_wrapper-0.3.5}/tests/test_resources/test_property_use_subresources.py

@@ -53,21 +53,41 @@ def test_use_details_add_revision():
 
 
 @respx.mock
-def test_use_details_revisions_with_date_window():
-    list_xml = """<?xml version="1.0"?><response status="Ok"><links/></response>"""
+def test_use_details_revisions_parses_useDetails_envelope():
+    """Regression: GET /propertyUse/{id}/useDetailsRevisions returns
+    <useDetails> (not <response>) with polymorphic use-detail children.
+
+    Body shape captured from the EPA's published useDetailsRevisions/get
+    docs. Asserts query params forward correctly and the typed children
+    are populated on the returned UseDetails.
+    """
+    list_xml = """<?xml version="1.0" encoding="UTF-8"?>
+<useDetails>
+    <totalGrossFloorArea units="Square Feet" id="24373669" currentAsOf="2004-01-01" temporary="false" default="N/A">
+        <value>12440</value>
+    </totalGrossFloorArea>
+    <numberOfComputers id="24371777" currentAsOf="2004-01-01" temporary="false" default="No">
+        <value>20</value>
+    </numberOfComputers>
+</useDetails>"""
 
     route = respx.get(f"{BASE}/propertyUse/13255076/useDetailsRevisions").mock(
         return_value=httpx.Response(200, content=list_xml)
     )
 
     client = EpaPmClient("user", "pass")
-    client.property_use.use_details.revisions(
+    result = client.property_use.use_details.revisions(
         13255076, current_as_of_start="2024-01-01", current_as_of_end="2024-12-31"
     )
 
     params = route.calls[0].request.url.params
     assert params.get("currentAsOfStart") == "2024-01-01"
     assert params.get("currentAsOfEnd") == "2024-12-31"
+    assert isinstance(result, UseDetails)
+    assert len(result.total_gross_floor_area) == 1
+    assert result.total_gross_floor_area[0].id == 24373669
+    assert len(result.number_of_computers) == 1
+    assert result.number_of_computers[0].id == 24371777
 
 
 @respx.mock

{epa_pm_api_wrapper-0.3.3 → epa_pm_api_wrapper-0.3.5}/uv.lock

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

epa_pm_api_wrapper-0.3.3/src/epa_pm_api_wrapper/models/building.py

@@ -1,11 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from .property_type import PropertyType
-
-
-@dataclass(kw_only=True)
-class Building(PropertyType):
-    class Meta:
-        name = "building"