EPA-PM-API-Wrapper 0.3.1__tar.gz → 0.3.2__tar.gz

epa_pm_api_wrapper-0.3.2/CHANGELOG/0.3.2.md

@@ -0,0 +1,20 @@
+# 0.3.2 (2026-05-07)
+
+### Fixed
+
+- **`consumption_data.add()`:** declared `response_type=Response`, but the EPA returns the created records inside a `<meterData>` envelope (with server-assigned `<id>` populated). Every successful POST raised `xsdata.exceptions.ParserError: Unknown property response:meterConsumption` even though the records were stored. The method now declares `response_type=MeterData` and returns the created records, so callers can read assigned IDs without a follow-up GET. Sync + async variants kept symmetric.
+- **`waste_data.add()`:** same bug, parallel fix. The EPA's published `meter/wasteData/post` docs return `<wasteDataList>` containing the created `<wasteData>` record(s). The method now declares `response_type=WasteDataList` and returns the created records with their IDs.
+
+### Documentation
+
+- Reworked `docs/api.md` from a single `::: epa_pm_api_wrapper` directive into a sectioned reference covering clients, exceptions, retry config, and one entry per resource module so the attribute-namespaced API surface (`client.account`, `client.property`, `client.meter`, …) actually renders in the published docs.
+- Tightened the `docs/usage.md` bulk-import recipe to read assigned IDs from the returned `MeterData` instead of the (now-nonexistent) `response.status`.
+- Moved the 2026 EPA Portfolio Manager XSD snapshot from `docs/_xml-schema/` to `schemas/` (it is a code-generation input, not docs content) and added a `CONTRIBUTING.md` note explaining provenance and refresh procedure.
+
+### Caller impact
+
+Any caller that swallowed the `ParserError` from `consumption_data.add()` or `waste_data.add()` to work around the bug should remove that workaround. Callers that branched on `Response.status` from these methods need to switch to checking the returned `MeterData` / `WasteDataList` (or simply rely on absence of an exception, which is the more idiomatic pattern).
+
+### Contributors
+
+[@harryw1](https://github.com/harryw1) (Harrison Weiss)

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/CONTRIBUTING.md

@@ -99,6 +99,15 @@ Ready to contribute? Here's how to set up EPA-PM-API-Wrapper for local developme
 
 7. Submit a pull request through the GitHub website.
 
+## Generated models
+
+The dataclasses in `src/epa_pm_api_wrapper/models/` are generated from the
+2026 EPA Portfolio Manager XSD snapshot vendored under `schemas/` (rooted
+at `schemas/main.xsd`) using [`xsdata`](https://xsdata.readthedocs.io/).
+If the EPA publishes an updated schema, refresh `schemas/` from
+[`portfoliomanager.energystar.gov/webservices`](https://portfoliomanager.energystar.gov/webservices)
+and regenerate before editing the generated modules by hand.
+
 ## Pull Request Guidelines
 
 Before you submit a pull request, check that it meets these guidelines:

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EPA-PM-API-Wrapper
-Version: 0.3.1
+Version: 0.3.2
 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.2/docs/api.md

@@ -0,0 +1,104 @@
+# API Reference
+
+The public surface is the items listed below, plus everything exported from
+`epa_pm_api_wrapper.__all__`. Each resource is bound to `EpaPmClient` and
+`EpaPmAsyncClient` under an attribute matching the snake-cased name (e.g.
+the methods documented on `AccountResource` are reached via
+`client.account.<method>`); async resources expose the same methods as
+coroutines.
+
+## Clients
+
+::: epa_pm_api_wrapper.client.EpaPmClient
+
+::: epa_pm_api_wrapper.client.EpaPmAsyncClient
+
+## Exceptions
+
+::: epa_pm_api_wrapper.exceptions
+
+## Retry configuration
+
+::: epa_pm_api_wrapper.retry.RetryConfig
+
+## Resources
+
+### Account — `client.account`
+
+::: epa_pm_api_wrapper.resources.account
+
+### Association — `client.association`
+
+::: epa_pm_api_wrapper.resources.association
+
+### Building — `client.building`
+
+::: epa_pm_api_wrapper.resources.building
+
+### Consumption data — `client.consumption_data`
+
+::: epa_pm_api_wrapper.resources.consumption_data
+
+### Custom metric — `client.custom_metric`
+
+::: epa_pm_api_wrapper.resources.custom_metric
+
+### Customer — `client.customer`
+
+::: epa_pm_api_wrapper.resources.customer
+
+### Data exchange — `client.data_exchange`
+
+::: epa_pm_api_wrapper.resources.data_exchange
+
+### Green power — `client.green_power`
+
+::: epa_pm_api_wrapper.resources.green_power
+
+### Home Energy Yardstick — `client.hey`
+
+::: epa_pm_api_wrapper.resources.hey
+
+### Hierarchy — `client.hierarchy`
+
+::: epa_pm_api_wrapper.resources.hierarchy
+
+### Identifier — `client.identifier`
+
+::: epa_pm_api_wrapper.resources.identifier
+
+### Meter — `client.meter`
+
+::: epa_pm_api_wrapper.resources.meter
+
+### Metrics — `client.metrics`
+
+::: epa_pm_api_wrapper.resources.metrics
+
+### Property — `client.property`
+
+::: epa_pm_api_wrapper.resources.property
+
+### Property use — `client.property_use`
+
+::: epa_pm_api_wrapper.resources.property_use
+
+### Report — `client.report`
+
+::: epa_pm_api_wrapper.resources.report
+
+### Share — `client.share`
+
+::: epa_pm_api_wrapper.resources.share
+
+### Target finder — `client.target_finder`
+
+::: epa_pm_api_wrapper.resources.target_finder
+
+### Verification — `client.verification`
+
+::: epa_pm_api_wrapper.resources.verification
+
+### Waste data — `client.waste_data`
+
+::: epa_pm_api_wrapper.resources.waste_data

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/docs/usage.md

@@ -228,8 +228,10 @@ with EpaPmClient(username, password) as client:
             # …more records up to 120 per call…
         ],
     )
-    response = client.consumption_data.add(meter_id, payload)
-    print(response.status)
+    created = client.consumption_data.add(meter_id, payload)
+    # The EPA echoes back each record with its server-assigned id populated.
+    for record in created.meter_consumption or []:
+        print(record.id, record.start_date, record.usage)
 ```
 
 ### Poll a report to completion
@@ -302,5 +304,7 @@ type is the concrete subtype.
 
 Every endpoint in the EPA Portfolio Manager web services API is bound to
 either a method or a sub-namespace on the client. See
-[the API reference](api.md) for the full surface, generated from the
-docstrings on each resource class.
+[the API reference](api.md) for the full surface — clients, exceptions,
+retry config, and one section per resource (`client.account`,
+`client.property`, `client.meter`, …) generated from the docstrings on
+each resource class.

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/justfile

@@ -99,7 +99,11 @@ clean-test:
 	rm -fr htmlcov/
 	rm -fr .pytest_cache
 
-# Publish to PyPI (manual alternative to GitHub Actions)
+# Publish to PyPI (manual alternative to GitHub Actions). Sources
+# ~/.zshenv.local so UV_PUBLISH_TOKEN (or equivalent) is available.
 publish:
+    #!/usr/bin/env zsh
+    set -euo pipefail
+    [[ -f ~/.zshenv.local ]] && source ~/.zshenv.local
     uv build
     uv publish

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/pyproject.toml

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

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/src/epa_pm_api_wrapper/cli.py

@@ -10,7 +10,7 @@ Each command takes ``--username`` / ``--password`` / ``--test`` (with matching
 variables, also picked up from a `.env` file in the working directory).
 """
 
-from typing import Annotated, Optional
+from typing import Annotated
 
 import typer
 from dotenv import load_dotenv
@@ -155,8 +155,8 @@ def get_consumption(
     username: Username,
     password: Password,
     page: Annotated[int, typer.Option(help="1-based page number (120 records per page)")] = 1,
-    start_date: Annotated[Optional[str], typer.Option(help="ISO 8601 start date (YYYY-MM-DD)")] = None,
-    end_date: Annotated[Optional[str], typer.Option(help="ISO 8601 end date (YYYY-MM-DD)")] = None,
+    start_date: Annotated[str | None, typer.Option(help="ISO 8601 start date (YYYY-MM-DD)")] = None,
+    end_date: Annotated[str | None, typer.Option(help="ISO 8601 end date (YYYY-MM-DD)")] = None,
     test: Test = False,
 ) -> None:
     """Get consumption records for a meter."""

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/src/epa_pm_api_wrapper/resources/consumption_data.py

@@ -26,9 +26,15 @@ class ConsumptionDataResource(Resource):
         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 add(self, meter_id: int, data: MeterData) -> MeterData:
+        """Add consumption data records to a meter.
+
+        Returns the created records with their server-assigned IDs populated;
+        callers can read ``meter_consumption[i].id`` to track them without a
+        follow-up GET. The EPA responds with a ``<meterData>`` envelope here,
+        not the usual ``<response>``.
+        """
+        return self._client._request("POST", f"meter/{meter_id}/consumptionData", data=data, response_type=MeterData)
 
     def update(self, consumption_data_id: int, data: MeterConsumption) -> Response:
         """Update a single consumption data record."""
@@ -95,9 +101,9 @@ class AsyncConsumptionDataResource(AsyncResource):
             "GET", f"meter/{meter_id}/consumptionData", params=params, response_type=MeterData
         )
 
-    async def add(self, meter_id: int, data: MeterData) -> Response:
+    async def add(self, meter_id: int, data: MeterData) -> MeterData:
         return await self._client._arequest(
-            "POST", f"meter/{meter_id}/consumptionData", data=data, response_type=Response
+            "POST", f"meter/{meter_id}/consumptionData", data=data, response_type=MeterData
         )
 
     async def update(self, consumption_data_id: int, data: MeterConsumption) -> Response:

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/src/epa_pm_api_wrapper/resources/waste_data.py

@@ -21,9 +21,16 @@ class WasteDataResource(Resource):
         params = {"page": page, "startDate": start_date, "endDate": end_date}
         return self._client._request("GET", f"meter/{meter_id}/wasteData", params=params, response_type=WasteDataList)
 
-    def add(self, meter_id: int, data: WasteData) -> Response:
-        """Add a waste data record to a meter."""
-        return self._client._request("POST", f"meter/{meter_id}/wasteData", data=data, response_type=Response)
+    def add(self, meter_id: int, data: WasteData) -> WasteDataList:
+        """Add a waste data record to a meter.
+
+        Returns a ``<wasteDataList>`` echoing the created record with its
+        server-assigned ``id`` populated; callers can read
+        ``result.waste_data[0].id`` without a follow-up GET. The EPA
+        responds with this envelope (not the usual ``<response>``) even for
+        a single-record POST.
+        """
+        return self._client._request("POST", f"meter/{meter_id}/wasteData", data=data, response_type=WasteDataList)
 
     def delete_range(self, meter_id: int, start_date: str, end_date: str) -> Response:
         """Delete waste data records on a meter within a date range."""
@@ -81,8 +88,10 @@ class AsyncWasteDataResource(AsyncResource):
             "GET", f"meter/{meter_id}/wasteData", params=params, response_type=WasteDataList
         )
 
-    async def add(self, meter_id: int, data: WasteData) -> Response:
-        return await self._client._arequest("POST", f"meter/{meter_id}/wasteData", data=data, response_type=Response)
+    async def add(self, meter_id: int, data: WasteData) -> WasteDataList:
+        return await self._client._arequest(
+            "POST", f"meter/{meter_id}/wasteData", data=data, response_type=WasteDataList
+        )
 
     async def delete_range(self, meter_id: int, start_date: str, end_date: str) -> Response:
         return await self._client._arequest(

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/tests/test_resources/test_consumption_data.py

@@ -7,7 +7,7 @@ import respx
 from xsdata.models.datatype import XmlDate
 
 from epa_pm_api_wrapper.client import EpaPmClient
-from epa_pm_api_wrapper.models import MeterConsumption, StatusType
+from epa_pm_api_wrapper.models import MeterConsumption, MeterData, StatusType
 
 BASE = EpaPmClient.LIVE_BASE_URL
 
@@ -54,6 +54,50 @@ def test_delete_range_passes_dates_as_query():
     assert params.get("endDate") == "2024-06-30"
 
 
+@respx.mock
+def test_add_returns_meter_data_with_assigned_ids():
+    """Regression: EPA returns <meterData> (not <response>) on POST.
+
+    Captured from the wstest environment; see BUGS.md #1 in the test repo.
+    Asserts the response parses as MeterData and surfaces server-assigned IDs.
+    """
+    add_xml = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<meterData>
+  <meterConsumption estimatedValue="false">
+    <id>900238341</id>
+    <cost>250</cost>
+    <startDate>2025-01-01</startDate>
+    <endDate>2025-01-31</endDate>
+    <usage>1234.56</usage>
+  </meterConsumption>
+  <meterConsumption estimatedValue="true">
+    <id>900238342</id>
+    <startDate>2025-02-01</startDate>
+    <endDate>2025-02-28</endDate>
+    <usage>2000</usage>
+  </meterConsumption>
+</meterData>"""
+
+    route = respx.post(f"{BASE}/meter/123/consumptionData").mock(return_value=httpx.Response(201, content=add_xml))
+
+    client = EpaPmClient("user", "pass")
+    payload = MeterData(
+        meter_consumption=[
+            MeterConsumption(
+                start_date=XmlDate(2025, 1, 1),
+                end_date=XmlDate(2025, 1, 31),
+                usage=Decimal("1234.56"),
+            ),
+        ],
+    )
+    result = client.consumption_data.add(123, payload)
+
+    assert route.called
+    assert isinstance(result, MeterData)
+    assert result.meter_consumption is not None
+    assert [r.id for r in result.meter_consumption] == [900238341, 900238342]
+
+
 @respx.mock
 def test_what_changed_for_customer():
     route = respx.get(f"{BASE}/customer/501362/meter/consumptionData/whatChanged").mock(

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/tests/test_resources/test_waste_data.py

@@ -1,8 +1,11 @@
+from decimal import Decimal
+
 import httpx
 import respx
+from xsdata.models.datatype import XmlDate
 
 from epa_pm_api_wrapper.client import EpaPmClient
-from epa_pm_api_wrapper.models import StatusType
+from epa_pm_api_wrapper.models import StatusType, WasteData, WasteDataList
 
 BASE = EpaPmClient.LIVE_BASE_URL
 
@@ -32,6 +35,47 @@ def test_list_with_date_range():
     assert len(data.waste_data) == 1
 
 
+@respx.mock
+def test_add_returns_waste_data_list_with_assigned_id():
+    """Regression: EPA returns <wasteDataList> (not <response>) on POST.
+
+    Body shape captured from the EPA's published wasteData/post endpoint
+    docs; mirrors the consumption_data.add() fix. Asserts the response
+    parses as WasteDataList and the created record's id is surfaced.
+    """
+    add_xml = """<?xml version="1.0" encoding="UTF-8"?>
+<wasteDataList>
+    <wasteData estimatedValue="true">
+        <id>783569362</id>
+        <startDate>2013-01-01</startDate>
+        <endDate>2013-01-31</endDate>
+        <quantity>50</quantity>
+        <cost>100</cost>
+        <disposalDestination>
+            <incinerationPercentage>25</incinerationPercentage>
+            <landfillPercentage>25</landfillPercentage>
+            <unknownDestPercentage>25</unknownDestPercentage>
+            <wasteToEnergyPercentage>25</wasteToEnergyPercentage>
+        </disposalDestination>
+    </wasteData>
+</wasteDataList>"""
+
+    route = respx.post(f"{BASE}/meter/123/wasteData").mock(return_value=httpx.Response(201, content=add_xml))
+
+    client = EpaPmClient("user", "pass")
+    payload = WasteData(
+        start_date=XmlDate(2013, 1, 1),
+        end_date=XmlDate(2013, 1, 31),
+        quantity=Decimal("50"),
+    )
+    result = client.waste_data.add(123, payload)
+
+    assert route.called
+    assert isinstance(result, WasteDataList)
+    assert result.waste_data is not None
+    assert result.waste_data[0].id == 783569362
+
+
 @respx.mock
 def test_delete_range_passes_dates_as_query():
     response_xml = """<?xml version="1.0"?><response status="Ok"/>"""

{epa_pm_api_wrapper-0.3.1 → epa_pm_api_wrapper-0.3.2}/uv.lock

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

epa_pm_api_wrapper-0.3.1/docs/api.md

@@ -1,3 +0,0 @@
-# API Reference
-
-::: epa_pm_api_wrapper