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

epa_pm_api_wrapper-0.3.6/CHANGELOG/0.3.6.md

@@ -0,0 +1,20 @@
+# 0.3.6 (2026-05-07)
+
+### Fixed
+
+- **`property_use.use_details.add_revision()` / `update()`** — the body must be the bare concrete use-detail element (e.g. `<weeklyOperatingHours>`, `<numberOfWorkers>`, `<totalGrossFloorArea>`); a `<useDetails>` envelope causes EPA to reject with HTTP 400. The `data` parameter type changes from `UseDetails` to `UseAttributeBase`, which truthfully tells callers "one record at a time" and ensures xsdata serializes the right root element. Sync + async kept symmetric.
+- **`AdditionalIdentifiers` / `AdditionalIdentifierTypes`** — paginated identifier-list responses include a `<links>` element that the strict xsdata parser rejected with `ParserError: Unknown property additionalIdentifiers:links`. Both models now expose an optional `links: LinksType` field so paginated GETs round-trip cleanly.
+
+### Added
+
+- **`epa_pm_api_wrapper.link_id(link)`** — public helper that returns a `LinkType`'s id, falling back from the `id` attribute to a trailing-integer parse of the `link` URL. Several EPA list/create responses populate the id only in the URL (e.g. `link="/meter/individual/2601"`), so callers previously had to hand-roll URL parsing. Re-exported from the top-level package.
+- **`Response.id` backfill on 4 create endpoints** — `report.templates.create`, `property.create_samples`, `property_use.use_details.add_revision`, and `green_power.onsite.add_detail` now populate `Response.id` from the first link when the top-level `<id>` is empty, matching the convention of every other `create()` method in the wrapper.
+- **EPA-quirk docstring notes** on nine methods covering: billboard-metric / password / property-representation `'No Selection Made'` and `'********'` GET-only sentinels, the `temporary` attribute requirement on use-detail writes, the per-(`propertyUseId`, `currentAsOf`) uniqueness rule, the monthly-metrics endpoint allowlist, the `numberOfBuildings > 1` precondition for building creation, HEY's rolling-12-month data window, and the `InternationalWeatherStation` US/CA exclusion.
+
+### Caller impact
+
+- **Breaking:** `property_use.use_details.add_revision(prop_use_id, data)` and `.update(use_details_id, data)` now accept `UseAttributeBase` (e.g. `WeeklyOperatingHours(...)`) instead of `UseDetails`. Callers that were passing `UseDetails(weekly_operating_hours=[...])` were already failing at runtime with HTTP 400, so the only mechanical migration is `UseDetails(weekly_operating_hours=[wh])` → `wh` (pass the single record directly).
+
+### Contributors
+
+[@harryw1](https://github.com/harryw1) (Harrison Weiss)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EPA-PM-API-Wrapper
-Version: 0.3.5
+Version: 0.3.6
 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.5 → epa_pm_api_wrapper-0.3.6}/pyproject.toml

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

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/__init__.py

@@ -1,5 +1,6 @@
 """Top-level package for EPA PM API Wrapper."""
 
+from epa_pm_api_wrapper._links import link_id
 from epa_pm_api_wrapper.client import EpaPmAsyncClient, EpaPmClient
 from epa_pm_api_wrapper.exceptions import (
     EpaErrorDetail,
@@ -27,4 +28,5 @@ __all__ = [
     "MeterData",
     "RetryConfig",
     "SharingResponse",
+    "link_id",
 ]

epa_pm_api_wrapper-0.3.6/src/epa_pm_api_wrapper/_links.py

@@ -0,0 +1,26 @@
+"""Link helpers — extract IDs from ``LinkType`` regardless of source quirks."""
+
+from __future__ import annotations
+
+import re
+
+from .models import LinkType
+
+_TAIL_RE = re.compile(r"/(\d+)/?$")
+
+
+def link_id(link: LinkType) -> int | None:
+    """Return the ID for a link, falling back to URL-tail parsing.
+
+    Some EPA list/create responses populate ``LinkType@id`` directly;
+    others embed the id only in the ``link`` URL (e.g.
+    ``/meter/individual/2601``). This helper tries the attribute first,
+    then the trailing-integer of the URL.
+    """
+    if link.id is not None:
+        return link.id
+    if link.link:
+        match = _TAIL_RE.search(link.link)
+        if match:
+            return int(match.group(1))
+    return None

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/models/additional_identifier_types.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 
 from .additional_identifier_type import AdditionalIdentifierType
+from .links_type import LinksType
 
 
 @dataclass(kw_only=True)
@@ -17,3 +18,10 @@ class AdditionalIdentifierTypes:
             "type": "Element",
         },
     )
+    links: None | LinksType = field(
+        default=None,
+        metadata={
+            "type": "Element",
+            "namespace": "",
+        },
+    )

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/models/additional_identifiers.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 
 from .additional_identifier import AdditionalIdentifier
+from .links_type import LinksType
 
 
 @dataclass(kw_only=True)
@@ -17,3 +18,10 @@ class AdditionalIdentifiers:
             "type": "Element",
         },
     )
+    links: None | LinksType = field(
+        default=None,
+        metadata={
+            "type": "Element",
+            "namespace": "",
+        },
+    )

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/resources/account.py

@@ -13,7 +13,19 @@ class AccountResource(Resource):
         return self._client._request("GET", "account", response_type=Account)
 
     def update(self, account_data: Account) -> Response:
-        """Update the authenticated user's account."""
+        """Update the authenticated user's account.
+
+        Note: GET may return the sentinel string ``'No Selection Made'`` for
+        ``billboardMetric`` when no metric has been selected. PUT rejects this
+        sentinel — pass ``None`` or a valid catalog value (see
+        ``billboard.catalog()``) instead.
+
+        Note: GET returns ``password`` as the masked sentinel ``'********'``.
+        Before calling ``update()``, set ``account.password`` to the real
+        password (the same one used to authenticate). The EPA appears to
+        ignore the password field when updating non-credential properties,
+        but it must pass schema validation on the wire.
+        """
         return self._client._request("PUT", "account", data=account_data, response_type=Response)
 
     def custom_fields(self, account_id: int) -> CustomFieldList:
@@ -27,7 +39,19 @@ class AsyncAccountResource(AsyncResource):
         return await self._client._arequest("GET", "account", response_type=Account)
 
     async def update(self, account_data: Account) -> Response:
-        """Update the authenticated user's account."""
+        """Update the authenticated user's account.
+
+        Note: GET may return the sentinel string ``'No Selection Made'`` for
+        ``billboardMetric`` when no metric has been selected. PUT rejects this
+        sentinel — pass ``None`` or a valid catalog value (see
+        ``billboard.catalog()``) instead.
+
+        Note: GET returns ``password`` as the masked sentinel ``'********'``.
+        Before calling ``update()``, set ``account.password`` to the real
+        password (the same one used to authenticate). The EPA appears to
+        ignore the password field when updating non-credential properties,
+        but it must pass schema validation on the wire.
+        """
         return await self._client._arequest("PUT", "account", data=account_data, response_type=Response)
 
     async def custom_fields(self, account_id: int) -> CustomFieldList:

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/resources/association.py

@@ -30,7 +30,13 @@ class PropertyMeterAssociationResource(Resource):
         )
 
     def set_many(self, property_id: int, data: MeterPropertyAssociationList) -> Response:
-        """Associate a batch of meters with a property in one call."""
+        """Associate a batch of meters with a property in one call.
+
+        Note: GET may return ``propertyRepresentationType='No Selection Made'``
+        when the property's representation type has not been chosen. POST
+        rejects this sentinel — pass ``None`` or a valid catalog value
+        instead.
+        """
         return self._client._request(
             "POST", f"association/property/{property_id}/meter", data=data, response_type=Response
         )
@@ -94,6 +100,13 @@ class AsyncPropertyMeterAssociationResource(AsyncResource):
         )
 
     async def set_many(self, property_id: int, data: MeterPropertyAssociationList) -> Response:
+        """Associate a batch of meters with a property in one call.
+
+        Note: GET may return ``propertyRepresentationType='No Selection Made'``
+        when the property's representation type has not been chosen. POST
+        rejects this sentinel — pass ``None`` or a valid catalog value
+        instead.
+        """
         return await self._client._arequest(
             "POST", f"association/property/{property_id}/meter", data=data, response_type=Response
         )

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/resources/building.py

@@ -17,7 +17,12 @@ class BuildingResource(Resource):
         return self._client._request("GET", f"building/{building_id}", response_type=Building)
 
     def create(self, property_id: int, building_data: Building) -> Response:
-        """Create a new building under a property."""
+        """Create a new building under a property.
+
+        Note: The parent property's ``numberOfBuildings`` must be greater
+        than 1 before a building can be added. Update the property first
+        via ``property.update`` if needed.
+        """
         return self._client._request(
             "POST", f"property/{property_id}/building", data=building_data, response_type=Response
         )
@@ -59,6 +64,12 @@ class AsyncBuildingResource(AsyncResource):
         return await self._client._arequest("GET", f"building/{building_id}", response_type=Building)
 
     async def create(self, property_id: int, building_data: Building) -> Response:
+        """Create a new building under a property.
+
+        Note: The parent property's ``numberOfBuildings`` must be greater
+        than 1 before a building can be added. Update the property first
+        via ``property.update`` if needed.
+        """
         return await self._client._arequest(
             "POST", f"property/{property_id}/building", data=building_data, response_type=Response
         )

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/resources/green_power.py

@@ -22,6 +22,7 @@ from epa_pm_api_wrapper.models import (
     Response,
 )
 
+from .._links import link_id
 from ._base import AsyncResource, Resource
 
 if TYPE_CHECKING:
@@ -79,12 +80,19 @@ class OnsiteRenewableResource(Resource):
 
     def add_detail(self, meter_id: int, data: OnsiteRenewableDetail) -> Response:
         """Add an onsite renewable detail record to a meter."""
-        return self._client._request(
+        resp = self._client._request(
             "POST",
             f"meter/{meter_id}/onsiteRenewableDetails",
             data=data,
             response_type=Response,
         )
+        if resp.id is None and resp.links and resp.links.link:
+            for link in resp.links.link:
+                candidate = link_id(link)
+                if candidate is not None:
+                    resp.id = candidate
+                    break
+        return resp
 
     def get_detail(self, detail_id: int) -> OnsiteRenewableDetail:
         """Get a specific onsite renewable detail record."""
@@ -183,12 +191,19 @@ class AsyncOnsiteRenewableResource(AsyncResource):
         )
 
     async def add_detail(self, meter_id: int, data: OnsiteRenewableDetail) -> Response:
-        return await self._client._arequest(
+        resp = await self._client._arequest(
             "POST",
             f"meter/{meter_id}/onsiteRenewableDetails",
             data=data,
             response_type=Response,
         )
+        if resp.id is None and resp.links and resp.links.link:
+            for link in resp.links.link:
+                candidate = link_id(link)
+                if candidate is not None:
+                    resp.id = candidate
+                    break
+        return resp
 
     async def get_detail(self, detail_id: int) -> OnsiteRenewableDetail:
         return await self._client._arequest(

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/resources/hey.py

@@ -13,10 +13,23 @@ 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."""
+        """Run Home Energy Yardstick against the supplied design and meter data.
+
+        Note: HEY scores against a rolling 12-month window of recent data.
+        Bills dated >~12 months in the past return
+        ``PROPERTY_DOES_NOT_HAVE_12_MONTHS_OF_METER_DATA``. Use bill dates
+        that end within roughly the last year.
+        """
         return self._client._request("POST", "hey", data=design, response_type=PropertyMetrics)
 
 
 class AsyncHeyResource(AsyncResource):
     async def evaluate(self, design: Hey) -> PropertyMetrics:
+        """Run Home Energy Yardstick against the supplied design and meter data.
+
+        Note: HEY scores against a rolling 12-month window of recent data.
+        Bills dated >~12 months in the past return
+        ``PROPERTY_DOES_NOT_HAVE_12_MONTHS_OF_METER_DATA``. Use bill dates
+        that end within roughly the last year.
+        """
         return await self._client._arequest("POST", "hey", data=design, response_type=PropertyMetrics)

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/resources/metrics.py

@@ -45,7 +45,13 @@ class MetricsResource(Resource):
         month: int,
         measurement_system: str = "EPA",
     ) -> PropertyMetrics:
-        """Get monthly metric values for a property."""
+        """Get monthly metric values for a property.
+
+        Note: The monthly endpoint accepts only metrics flagged for monthly
+        reporting — typically those whose ``name`` ends in ``Monthly`` in
+        the ``report.metrics()`` catalog. Passing a metric only valid for
+        ``metrics.get`` (e.g. ``siteTotal``) returns ``EpaPmApiError(-200)``.
+        """
         return self._client._request(
             "GET",
             f"property/{property_id}/metrics/monthly",
@@ -130,6 +136,13 @@ class AsyncMetricsResource(AsyncResource):
         month: int,
         measurement_system: str = "EPA",
     ) -> PropertyMetrics:
+        """Get monthly metric values for a property.
+
+        Note: The monthly endpoint accepts only metrics flagged for monthly
+        reporting — typically those whose ``name`` ends in ``Monthly`` in
+        the ``report.metrics()`` catalog. Passing a metric only valid for
+        ``metrics.get`` (e.g. ``siteTotal``) returns ``EpaPmApiError(-200)``.
+        """
         return await self._client._arequest(
             "GET",
             f"property/{property_id}/metrics/monthly",

{epa_pm_api_wrapper-0.3.5 → epa_pm_api_wrapper-0.3.6}/src/epa_pm_api_wrapper/resources/property.py

@@ -32,6 +32,7 @@ from epa_pm_api_wrapper.models import (
     Response,
 )
 
+from .._links import link_id
 from ._base import AsyncResource, Resource
 
 if TYPE_CHECKING:
@@ -96,7 +97,12 @@ class BillboardMetricResource(Resource):
         )
 
     def update(self, property_id: int, data: BillboardMetricSetting) -> Response:
-        """Update the authenticated account's billboard metric setting for a property."""
+        """Update the authenticated account's billboard metric setting for a property.
+
+        Note: GET may return the sentinel string ``'No Selection Made'`` when
+        no metric has been selected. PUT rejects this sentinel — pass ``None``
+        or a valid catalog value (see ``billboard.catalog()``) instead.
+        """
         return self._client._request(
             "PUT", f"property/{property_id}/billboardMetricSetting", data=data, response_type=Response
         )
@@ -110,7 +116,12 @@ class BillboardMetricResource(Resource):
         )
 
     def update_for_customer(self, customer_id: int, property_id: int, data: BillboardMetricSetting) -> Response:
-        """Update a connected customer's billboard metric setting for a property."""
+        """Update a connected customer's billboard metric setting for a property.
+
+        Note: GET may return the sentinel string ``'No Selection Made'`` when
+        no metric has been selected. PUT rejects this sentinel — pass ``None``
+        or a valid catalog value (see ``billboard.catalog()``) instead.
+        """
         return self._client._request(
             "PUT",
             f"customer/{customer_id}/property/{property_id}/billboardMetricSetting",
@@ -145,7 +156,12 @@ class PgpResource(Resource):
 
 class InternationalWeatherStationResource(Resource):
     def list(self, country: str | None = None, page: int | None = None) -> InternationalWeatherStationList:
-        """List international weather stations, optionally filtered by ``country``."""
+        """List international weather stations, optionally filtered by ``country``.
+
+        Note: This endpoint excludes US and Canadian stations — EPA returns
+        ``HTTP 400 -200`` for ``country='US'`` or ``country='CA'``. Domestic
+        NOAA stations are assigned automatically based on property address.
+        """
         return self._client._request(
             "GET",
             "property/internationalWeatherStation/list",
@@ -250,18 +266,26 @@ class PropertyResource(Resource):
         if major_release_version is not None and create_count is not None:
             raise ValueError("Pass either major_release_version or create_count, not both")
         if major_release_version is not None:
-            return self._client._request(
+            resp = self._client._request(
                 "POST",
                 f"createSampleProperties/{major_release_version}",
                 params={"countryCode": country_code},
                 response_type=Response,
             )
-        return self._client._request(
-            "POST",
-            "createSampleProperties",
-            params={"countryCode": country_code, "createCount": create_count},
-            response_type=Response,
-        )
+        else:
+            resp = self._client._request(
+                "POST",
+                "createSampleProperties",
+                params={"countryCode": country_code, "createCount": create_count},
+                response_type=Response,
+            )
+        if resp.id is None and resp.links and resp.links.link:
+            for link in resp.links.link:
+                candidate = link_id(link)
+                if candidate is not None:
+                    resp.id = candidate
+                    break
+        return resp
 
 
 class AsyncPropertyDesignResource(AsyncResource):
@@ -307,6 +331,12 @@ class AsyncBillboardMetricResource(AsyncResource):
         )
 
     async def update(self, property_id: int, data: BillboardMetricSetting) -> Response:
+        """Update the authenticated account's billboard metric setting for a property.
+
+        Note: GET may return the sentinel string ``'No Selection Made'`` when
+        no metric has been selected. PUT rejects this sentinel — pass ``None``
+        or a valid catalog value (see ``billboard.catalog()``) instead.
+        """
         return await self._client._arequest(
             "PUT", f"property/{property_id}/billboardMetricSetting", data=data, response_type=Response
         )
@@ -319,6 +349,12 @@ class AsyncBillboardMetricResource(AsyncResource):
         )
 
     async def update_for_customer(self, customer_id: int, property_id: int, data: BillboardMetricSetting) -> Response:
+        """Update a connected customer's billboard metric setting for a property.
+
+        Note: GET may return the sentinel string ``'No Selection Made'`` when
+        no metric has been selected. PUT rejects this sentinel — pass ``None``
+        or a valid catalog value (see ``billboard.catalog()``) instead.
+        """
         return await self._client._arequest(
             "PUT",
             f"customer/{customer_id}/property/{property_id}/billboardMetricSetting",
@@ -348,6 +384,12 @@ class AsyncPgpResource(AsyncResource):
 
 class AsyncInternationalWeatherStationResource(AsyncResource):
     async def list(self, country: str | None = None, page: int | None = None) -> InternationalWeatherStationList:
+        """List international weather stations, optionally filtered by ``country``.
+
+        Note: This endpoint excludes US and Canadian stations — EPA returns
+        ``HTTP 400 -200`` for ``country='US'`` or ``country='CA'``. Domestic
+        NOAA stations are assigned automatically based on property address.
+        """
         return await self._client._arequest(
             "GET",
             "property/internationalWeatherStation/list",
@@ -436,15 +478,23 @@ class AsyncPropertyResource(AsyncResource):
         if major_release_version is not None and create_count is not None:
             raise ValueError("Pass either major_release_version or create_count, not both")
         if major_release_version is not None:
-            return await self._client._arequest(
+            resp = await self._client._arequest(
                 "POST",
                 f"createSampleProperties/{major_release_version}",
                 params={"countryCode": country_code},
                 response_type=Response,
             )
-        return await self._client._arequest(
-            "POST",
-            "createSampleProperties",
-            params={"countryCode": country_code, "createCount": create_count},
-            response_type=Response,
-        )
+        else:
+            resp = await self._client._arequest(
+                "POST",
+                "createSampleProperties",
+                params={"countryCode": country_code, "createCount": create_count},
+                response_type=Response,
+            )
+        if resp.id is None and resp.links and resp.links.link:
+            for link in resp.links.link:
+                candidate = link_id(link)
+                if candidate is not None:
+                    resp.id = candidate
+                    break
+        return resp

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

@@ -21,6 +21,7 @@ from epa_pm_api_wrapper.models import (
     UseDetails,
 )
 
+from .._links import link_id
 from ._base import AsyncResource, Resource
 
 if TYPE_CHECKING:
@@ -34,11 +35,35 @@ class UseDetailsResource(Resource):
     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(
+    def add_revision(self, property_use_id: int, data: UseAttributeBase) -> Response:
+        """Add a new use-detail revision to a property use.
+
+        ``data`` is a single concrete use-detail record (e.g.
+        :class:`WeeklyOperatingHours`, :class:`NumberOfWorkers`,
+        :class:`TotalGrossFloorArea`) — NOT a :class:`UseDetails` envelope.
+        The body must be the bare child element (e.g.
+        ``<weeklyOperatingHours>...</weeklyOperatingHours>``); a
+        ``<useDetails>`` wrapper causes EPA to reject with HTTP 400.
+
+        Note: Set ``temporary=False`` on the data record (or ``True`` for
+        temporary values). EPA rejects writes without this attribute even
+        though the XSD allows omission.
+
+        Note: Each (``propertyUseId``, ``currentAsOf``) pair must be unique.
+        Posting a second revision for an existing date returns
+        ``EpaPmApiError(-200, 'matches a date that has already been provided')``.
+        Use a distinct date or update the existing record via ``update()``.
+        """
+        resp = self._client._request(
             "POST", f"propertyUse/{property_use_id}/useDetails", data=data, response_type=Response
         )
+        if resp.id is None and resp.links and resp.links.link:
+            for link in resp.links.link:
+                candidate = link_id(link)
+                if candidate is not None:
+                    resp.id = candidate
+                    break
+        return resp
 
     def revisions(
         self,
@@ -70,8 +95,19 @@ class UseDetailsResource(Resource):
         """
         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."""
+    def update(self, use_details_id: int, data: UseAttributeBase) -> Response:
+        """Correct a single use-details record.
+
+        ``data`` is the concrete use-detail subtype (e.g.
+        :class:`WeeklyOperatingHours`, :class:`NumberOfWorkers`,
+        :class:`TotalGrossFloorArea`) — NOT a :class:`UseDetails` envelope.
+        The body must be the bare child element; a ``<useDetails>`` wrapper
+        causes EPA to reject with HTTP 400.
+
+        Note: Set ``temporary=False`` on the data record (or ``True`` for
+        temporary values). EPA rejects writes without this attribute even
+        though the XSD allows omission.
+        """
         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:
@@ -168,7 +204,16 @@ class PropertyUseResource(Resource):
         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."""
+        """Update a property use's name.
+
+        EPA's PUT body schema differs from the POST schema: pass a bare
+        :class:`PropertyUse` envelope (``PropertyUse(name="…")``) — NOT
+        the concrete subtype like :class:`Parking` or :class:`Office`
+        returned by :meth:`get`. The wire body must be
+        ``<propertyUse><name>...</name></propertyUse>``; sending
+        ``<parking>...</parking>`` or any other concrete root element is
+        rejected by EPA. Per the XSD this endpoint updates the name only.
+        """
         return self._client._request("PUT", f"propertyUse/{property_use_id}", data=data, response_type=Response)
 
     def delete(self, property_use_id: int) -> Response:
@@ -177,10 +222,34 @@ class PropertyUseResource(Resource):
 
 
 class AsyncUseDetailsResource(AsyncResource):
-    async def add_revision(self, property_use_id: int, data: UseDetails) -> Response:
-        return await self._client._arequest(
+    async def add_revision(self, property_use_id: int, data: UseAttributeBase) -> Response:
+        """Add a new use-detail revision to a property use.
+
+        ``data`` is a single concrete use-detail record (e.g.
+        :class:`WeeklyOperatingHours`, :class:`NumberOfWorkers`,
+        :class:`TotalGrossFloorArea`) — NOT a :class:`UseDetails` envelope.
+        The body must be the bare child element; a ``<useDetails>`` wrapper
+        causes EPA to reject with HTTP 400.
+
+        Note: Set ``temporary=False`` on the data record (or ``True`` for
+        temporary values). EPA rejects writes without this attribute even
+        though the XSD allows omission.
+
+        Note: Each (``propertyUseId``, ``currentAsOf``) pair must be unique.
+        Posting a second revision for an existing date returns
+        ``EpaPmApiError(-200, 'matches a date that has already been provided')``.
+        Use a distinct date or update the existing record via ``update()``.
+        """
+        resp = await self._client._arequest(
             "POST", f"propertyUse/{property_use_id}/useDetails", data=data, response_type=Response
         )
+        if resp.id is None and resp.links and resp.links.link:
+            for link in resp.links.link:
+                candidate = link_id(link)
+                if candidate is not None:
+                    resp.id = candidate
+                    break
+        return resp
 
     async def revisions(
         self,
@@ -201,7 +270,18 @@ class AsyncUseDetailsResource(AsyncResource):
             await self._client._arequest_polymorphic("GET", f"useDetails/{use_details_id}"),
         )
 
-    async def update(self, use_details_id: int, data: UseDetails) -> Response:
+    async def update(self, use_details_id: int, data: UseAttributeBase) -> Response:
+        """Correct a single use-details record.
+
+        ``data`` is the concrete use-detail subtype — NOT a
+        :class:`UseDetails` envelope. The body must be the bare child
+        element; a ``<useDetails>`` wrapper causes EPA to reject with
+        HTTP 400.
+
+        Note: Set ``temporary=False`` on the data record (or ``True`` for
+        temporary values). EPA rejects writes without this attribute even
+        though the XSD allows omission.
+        """
         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:
@@ -277,6 +357,14 @@ class AsyncPropertyUseResource(AsyncResource):
         )
 
     async def update(self, property_use_id: int, data: PropertyUse) -> Response:
+        """Update a property use's name.
+
+        EPA's PUT body schema differs from the POST schema: pass a bare
+        :class:`PropertyUse` envelope (``PropertyUse(name="…")``) — NOT
+        the concrete subtype returned by :meth:`get`. The wire body must
+        be ``<propertyUse><name>...</name></propertyUse>``; sending a
+        concrete-type root element is rejected by EPA.
+        """
         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: