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

{epa_pm_api_wrapper-0.3.6 → epa_pm_api_wrapper-0.4.0}/.gitignore

@@ -52,3 +52,8 @@ site/
 # IDE files
 # .idea/
 # .vscode/
+
+.claude/
+
+# Local-only probing/debugging scripts
+scripts/_*.py

epa_pm_api_wrapper-0.4.0/CHANGELOG/0.4.0.md

@@ -0,0 +1,29 @@
+# 0.4.0 (2026-05-07)
+
+### Changed
+
+- **Breaking — `client.report.download(...)` return type.** Both the sync and async `download()` now return a `DownloadResult` dataclass (`content`, `content_type`, `filename`, `size`) instead of bare `bytes`. Previously the wrapper dropped EPA's response headers and handed back only the body, which forced callers to guess a content type / extension based on the requested `report_format`. EPA actually returns `application/zip` for large XML results and for `EXCEL`, so a caller hardcoding `application/xml` / `.xml` on top of the bytes would mislabel zip payloads — exactly the trap a downstream consumer hit. Forwarding EPA's `Content-Type` and `Content-Disposition` lets routes serve or save the file as whatever EPA actually sent.
+
+### Added
+
+- **`DownloadResult`** dataclass, exported from the top-level package, with `content: bytes`, `content_type: str | None`, `filename: str | None` (parsed from `Content-Disposition`, including RFC 6266 `filename*`), and `size: int` (actual byte length, since EPA sometimes omits `Content-Length`).
+
+### Caller impact
+
+- **Breaking:** any caller doing `data = client.report.download(rid)` and then treating `data` as bytes must change to `result.content`. Mechanical migration:
+
+  ```python
+  # before
+  xml_bytes = client.report.download(rid, report_format="XML")
+  save(xml_bytes)
+
+  # after
+  result = client.report.download(rid, report_format="XML")
+  save(result.content, content_type=result.content_type, filename=result.filename)
+  ```
+
+  Async is identical (`await client.report.download(...)` → `DownloadResult`).
+
+### Contributors
+
+[@harryw1](https://github.com/harryw1) (Harrison Weiss)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: EPA-PM-API-Wrapper
-Version: 0.3.6
+Version: 0.4.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.3.6 → epa_pm_api_wrapper-0.4.0}/docs/api.md

@@ -73,6 +73,11 @@ coroutines.
 
 ### Metrics — `client.metrics`
 
+For the catalog of valid metric *names* — what to pass in
+`metrics=[...]` — see the [Metrics guide](metrics.md), which covers
+runtime discovery via `client.report.metrics()`, a curated reference
+table, and which endpoint accepts which metric.
+
 ::: epa_pm_api_wrapper.resources.metrics
 
 ### Property — `client.property`

epa_pm_api_wrapper-0.4.0/docs/cli.md

@@ -0,0 +1,136 @@
+# Command-line interface
+
+The package ships with a `typer`-based CLI for ad-hoc lookups against the
+Portfolio Manager API. It is intentionally read-only and limited to the
+most common exploration queries — for the full ~70-endpoint surface,
+instantiate `EpaPmClient` directly from your application.
+
+## Invocation
+
+The console script is registered as `epa_pm_api_wrapper`:
+
+```sh
+epa_pm_api_wrapper --help
+epa_pm_api_wrapper account
+epa_pm_api_wrapper get-property 19939329 --test
+```
+
+If the script isn't on your `PATH`, fall back to module form (works the
+same way):
+
+```sh
+uv run python -m epa_pm_api_wrapper account
+```
+
+## Authentication
+
+Every command takes the same three options:
+
+| Flag           | Env var            | Notes                                                         |
+| -------------- | ------------------ | ------------------------------------------------------------- |
+| `--username`   | `EPA_PM_USERNAME`  | EPA Portfolio Manager username.                               |
+| `--password`   | `EPA_PM_PASSWORD`  | EPA password (input is hidden when prompted on the terminal). |
+| `--test`       | `EPA_PM_TEST`      | Switch to `wstest`; default is the live environment.          |
+
+Precedence:
+
+1. **`.env` in the current working directory** — loaded by `python-dotenv`
+   on startup with `override=True`, so `.env` wins over any matching
+   variable already set in the shell environment. See `.env.example` in
+   the repo root.
+2. **Process environment variables** — used when `.env` is absent or
+   doesn't define the variable.
+3. **Explicit CLI flags** — `--username`, `--password`, `--test` override
+   anything from the environment for that single invocation.
+4. **Interactive prompt** — if `--username` / `--password` resolve to
+   nothing after the previous steps, `typer` prompts on the terminal.
+
+## Output
+
+All commands print to the terminal via [`rich`](https://rich.readthedocs.io/) —
+either a labelled details block (for single-resource fetches like
+`account`, `get-property`, `get-meter`) or a `rich.Table` for list
+endpoints. Tables are not machine-friendly; pipe through `tee` and parse
+manually if needed, or call the API from Python for structured output.
+
+## Exit codes
+
+The CLI catches every exception inside each command and prints a red
+`Error:` line, then returns the typer default exit code. It does **not**
+currently propagate non-zero exit codes on failure — if you script around
+the CLI, parse stderr/stdout for an `Error:` prefix or (better) use the
+Python client and branch on `EpaPmApiError`.
+
+## Commands
+
+All commands are listed below. Run `epa_pm_api_wrapper <command> --help`
+for the full per-command flag list.
+
+### Account
+
+`account`
+:   Print the authenticated user's account ID, username, organization
+    name, and primary business.
+
+### Properties
+
+`list-properties ACCOUNT_ID`
+:   Tabulate properties under the given account ID.
+
+`get-property PROPERTY_ID`
+:   Print a single property's name, primary function, and address.
+
+`list-property-uses PROPERTY_ID`
+:   Tabulate property uses defined under a property.
+
+`list-buildings PROPERTY_ID`
+:   Tabulate buildings under a property.
+
+### Meters and consumption
+
+`list-meters PROPERTY_ID`
+:   Tabulate meters on a property.
+
+`get-meter METER_ID`
+:   Print a single meter's name, type, unit, and in-use flag.
+    Auto-detects energy vs. waste meters.
+
+`get-consumption METER_ID [--page N] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD]`
+:   Tabulate consumption records for a meter (one page of up to 120
+    records per call, default `--page 1`).
+
+### Connections and shares
+
+`list-customers`
+:   Tabulate customers connected to your account.
+
+`list-pending-shares`
+:   Print counts of pending property shares, meter shares, and account
+    connection requests waiting on your action.
+
+### Catalogs
+
+`list-edu PROPERTY_ID`
+:   List Electric Distribution Utilities available for a property.
+
+`list-federal-agencies`
+:   List federal agencies (catalog).
+
+`list-egrid-subregions`
+:   List eGrid subregions (catalog).
+
+### Reporting
+
+`list-reports`
+:   Tabulate reports in your account.
+
+`list-report-templates`
+:   Tabulate report templates available to your account.
+
+## Going beyond the CLI
+
+The CLI deliberately covers only the common cases. Anything not listed
+above (creating properties or meters, accepting shares, polling reports
+to completion, fetching metrics, bulk-importing data) is one or two
+lines of Python through `EpaPmClient` — see [Usage](usage.md) for
+worked examples.

epa_pm_api_wrapper-0.4.0/docs/errors.md

@@ -0,0 +1,297 @@
+# Errors
+
+The Portfolio Manager API has two error layers stacked on top of each
+other: the standard HTTP status codes (4xx/5xx), and an EPA-specific
+*application error* envelope returned in the response body for
+`<response status="Error">` payloads. This wrapper surfaces both through
+a single exception type.
+
+## How errors surface
+
+Every non-2xx response raises a subclass of `EpaPmError`:
+
+```python
+from epa_pm_api_wrapper.exceptions import (
+    EpaErrorDetail,
+    EpaPmApiError,
+    EpaPmAuthError,
+    EpaPmError,
+)
+```
+
+| Exception        | Raised on                                     | Notes                                                                   |
+| ---------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
+| `EpaPmAuthError` | HTTP 401                                      | Subclass of `EpaPmApiError`. Message reminds you to check creds + env.  |
+| `EpaPmApiError`  | All other non-2xx responses                   | Carries `status_code`, `errors`, `error_number`, and `response_text`.   |
+| `EpaPmError`     | (base class)                                  | Catch-all for both — useful for blanket `except` blocks.                |
+
+`EpaPmApiError` is a structured exception, not a string-formatted one.
+Branch on its attributes instead of regexing the message:
+
+```python
+from epa_pm_api_wrapper import EpaPmApiError
+
+try:
+    prop = client.property.get(property_id)
+except EpaPmApiError as e:
+    if e.status_code == 404:
+        # Resource doesn't exist — distinct from "you don't have access" (403).
+        return None
+    if e.error_number == -200 and "not a valid metric" in (e.errors[0].error_description or ""):
+        # Metric name rejected — likely typo or wrong endpoint family.
+        return None
+    raise
+```
+
+### Attributes
+
+| Attribute       | Type                       | Meaning                                                                                                |
+| --------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `status_code`   | `int`                      | The HTTP status code (e.g. `400`, `403`, `429`).                                                       |
+| `response_text` | `str`                      | The raw response body (XML or plain text). Useful for diagnostics; don't log credentials in production.|
+| `errors`        | `list[EpaErrorDetail]`     | Parsed `<error>` elements from the EPA error envelope; empty if the body wasn't structured XML.        |
+| `error_number`  | `int \| None`              | The EPA error number when there's exactly one — handy for `if e.error_number == -200:`. `None` if multiple errors are present. |
+
+For multi-error responses, iterate `errors`:
+
+```python
+for detail in e.errors:
+    print(detail.error_number, detail.error_description)
+```
+
+> **Caveat.** The error_description strings in the tables below are the
+> exact bytes EPA's test environment returned at the time of writing.
+> They are not part of any published contract and can change between
+> Portfolio Manager releases. Treat them as informational — match on
+> `status_code` + `error_number` first, and only fall back to substring
+> checks on the description when you must.
+
+## HTTP status codes (transport layer)
+
+These come from the EPA's published [Error Codes reference](https://portfoliomanager.energystar.gov/webservices/home/errors).
+The wrapper retries `429`, `502`, `503`, `504` automatically — see
+[Retries](usage.md#retries).
+
+| Status | When raised                                              | Suggested handling                                                          |
+| ------ | -------------------------------------------------------- | --------------------------------------------------------------------------- |
+| 400    | Bad request; almost always carries an EPA application error. | Inspect `error_number` — see the next table.                                |
+| 401    | Auth credentials missing or invalid.                     | `EpaPmAuthError`; check env + credentials. Don't retry.                     |
+| 403    | You're trying to read/write data you don't have access to. | Confirm the share/connection state via `client.share.*`. Don't retry.       |
+| 404    | Resource doesn't exist (or never existed).               | Distinct from 403 — surface as a domain-level "not found" if appropriate.   |
+| 405    | HTTP method not supported on this URL.                   | Programming error in the wrapper — please file a bug.                       |
+| 406    | Requested MIME type is not supported.                    | Don't override `Accept`; let the wrapper handle content negotiation.        |
+| 415    | Unsupported `Content-Type` on the request.               | Same as above — usually only triggered by injected `http_client` overrides. |
+| 429    | Rate limited.                                            | Retried automatically (honoring `Retry-After`); consider lowering concurrency.|
+| 500    | Internal server error.                                   | Retry sparingly; if persistent, escalate to EPA.                            |
+| 502    | Maintenance / upstream gateway error.                    | Retried automatically.                                                      |
+| 503    | Service unavailable.                                     | Retried automatically.                                                      |
+| 504    | Upstream timeout.                                        | Retried automatically.                                                      |
+
+## EPA application errors (the body envelope)
+
+When EPA returns an XML error body it looks like this:
+
+```xml
+<response status="Error">
+  <errors>
+    <error errorNumber="-200" errorDescription="nonExistentMetric not a valid metric."/>
+  </errors>
+</response>
+```
+
+The wrapper parses this into `errors=[EpaErrorDetail(error_number=-200,
+error_description="nonExistentMetric not a valid metric.")]` and
+exposes `error_number=-200` (when there's exactly one). The XSD declares
+`errorNumber` as a string, but EPA always sends integers in practice;
+the wrapper coerces with `int()` and falls back to `None` on the
+unlikely chance EPA ever ships a non-integer.
+
+A single response can contain multiple `<error>` entries — EPA does
+this for create/update validation failures so you see every problem at
+once. In that case `error_number` is `None`; iterate `errors` instead.
+
+### How `error_number` actually relates to HTTP status
+
+EPA's published [Error Codes](https://portfoliomanager.energystar.gov/webservices/home/errors)
+page documents two reserved negative codes — they are *categories*, not
+specific failures:
+
+| `error_number` | Meaning                                                                                |
+| -------------- | -------------------------------------------------------------------------------------- |
+| `-100`         | Submitted XML did not validate against the corresponding schema.                       |
+| `-200`         | An application-specific error. Read `error_description` for the actual condition.      |
+
+In practice — confirmed by probing the test environment directly — the
+wire pattern is:
+
+| HTTP status | Typical `error_number`            | What it means                                              |
+| ----------- | --------------------------------- | ---------------------------------------------------------- |
+| 400         | `-200` (often) or `-100` (schema) | Bad request; either an application validation failure or schema validation failure. |
+| 400         | *multiple `-200` entries*         | Create/update validation failure with every issue listed.  |
+| 401         | *(no envelope — HTML body)*       | Auth failure. `errors` will be `[]`; check `status_code`.  |
+| 404         | `404` (echoes the HTTP status)    | Resource doesn't exist. `error_description` is the human-readable cause (e.g. `"Property does not exist."`); occasionally an empty string parsed as `None`. |
+
+The 404 case is the surprising one: EPA reuses the HTTP status as the
+EPA `errorNumber` rather than a dedicated code. The legacy mention of
+`error_number=10` for "invalid property" is **not** what the test
+environment returns today — it now sends `errorNumber="404"
+errorDescription="Property does not exist."`. Branch on
+`status_code == 404` first, and only inspect `error_number` for further
+disambiguation if you really need to.
+
+### `-100` schema-validation subcases observed
+
+Generated by sending a malformed payload that the EPA rejects against
+its XSD before any business logic runs.
+
+| Triggering call                                                                | `error_description` fragment(s)                                                                                                                                                                                                                                                                                              | Notes                                                                                                                                                                                |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `client.property.create(account_id, sparse Property)` (missing required tags)  | EPA returned six `-200` entries instead of `-100` — every missing required field is reported as its own application error: `"Please provide the year that this property/building was built."`, `"Please provide the address."`, `"Please select your property's primary function."`, `"Please indicate if the gross floor area you have provided is square feet or square meters."`, `"Please select your property's construction status."`, `"Please provide the gross floor area."`. | Confirms EPA prefers the `-200` envelope with friendly per-field messages over the catch-all `-100`. Iterate `e.errors` to surface every missing field; `e.error_number` is `None`. |
+
+In this wrapper's experience — including all probes against the test
+environment — the EPA almost never returns a literal `-100`. Instead it
+prefers a `-200` payload with one `<error>` per validation problem
+(see the table above). If you do see `-100`, the body almost certainly
+got past the wrapper's serializer in a malformed state — most often
+because a custom `http_client` injected raw bytes rather than going
+through `EpaPmClient`'s xsdata-backed serialization. File an issue.
+
+### `-200` application-error subcases observed
+
+These are the ones you'll see from real callers. All surface as
+`EpaPmApiError(status_code=400, error_number=-200,
+errors=[EpaErrorDetail(error_number=-200, error_description="…")])`
+unless otherwise noted.
+
+#### Metrics endpoints
+
+| Triggering call                                                          | `error_description`                                | Suggested handling                                                                                                                                |
+| ------------------------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.metrics.get(pid, ["nonExistentMetric"], 2025, 12)`               | `"nonExistentMetric not a valid metric."`          | Look up the catalog with `client.report.metrics()` and check the metric name. See [Metrics guide](metrics.md#which-endpoint-accepts-which-metric).|
+| `client.metrics.monthly(pid, ["score"], 2025, 12)`                       | `"score not a valid metric."`                      | The monthly endpoint requires metrics whose name ends in `Monthly`; `score` only exists on `metrics.get`. There is no `scoreMonthly`.             |
+| `client.metrics.get(pid, ["siteIntensity"], 2025, 13)`                   | `"Invalid month and year combination"`             | Validate `month ∈ 1..12` and a reasonable `year` before calling.                                                                                  |
+
+> Notable non-errors observed:
+>
+> - `client.metrics.get(pid, ["siteIntensity"], 1900, 1)` — accepted; returns the metric with `value=None`. The EPA does **not** reject historical years client-side.
+> - `client.metrics.use_details(pid, ["score"], …)` — accepted; the use-details endpoint is permissive about the metric name and returns whatever use-detail metrics it has data for, ignoring an unknown name. Don't rely on this to validate metric names.
+> - `client.metrics.design(pid, ["score"], …)` — accepted; returns `score` with `value=None` rather than rejecting it. To be sure a metric is design-eligible, filter `client.report.metrics()` by group.
+> - `client.metrics.get(pid, "", year, month)` — accepted; an empty `PM-Metrics` header just yields a metrics envelope with no `<metric>` children.
+
+#### Weather stations
+
+| Triggering call                                            | `error_description`                                                                                                                       | Suggested handling                                                                                          |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `client.property.weather_station.list(country='US')`       | `"US and CA weather stations are not available through this service. Please refer to the National Climatic Data Center (NCDC) for this information."` | This endpoint excludes US/Canada — domestic NOAA stations are auto-assigned based on the property address. |
+| `client.property.weather_station.list(country='CA')`       | (same as above)                                                                                                                            | (same)                                                                                                       |
+
+> Notable non-error: `client.property.weather_station.list(country='ZZ')`
+> — accepted; returns an empty list rather than rejecting unknown
+> country codes. Don't rely on the API to validate country codes.
+
+#### Reports
+
+| Triggering call                                | `error_description`                                          | Suggested handling                                                                                                |
+| ---------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `client.report.download(rid)` before generation| `"The report has no results and should be generated."`       | Call `client.report.generate(rid)` first, then poll `client.report.status(rid)` until ready before downloading.   |
+
+> Notes:
+>
+> - `client.report.generate(rid)` on an already-generated report **succeeds** — it re-runs the report and returns a fresh `Response`. There is no "already generated" application error to handle.
+> - `client.report.download(rid)` after a successful generation returns a `DownloadResult` with the raw body, the EPA-supplied `content_type`, and an attachment `filename` when present (no error). EPA may serve `application/zip` for large XML results or for `EXCEL`, so prefer `result.content_type` over assuming `.xml`. Once the report has been generated at least once, the "no results" error from above no longer applies.
+
+#### Property use-details revisions
+
+Documented from prior real-world observation (not re-probed here to
+avoid creating revision detritus on the test account):
+
+| Triggering call                                              | `error_description` fragment           | Notes                                                                                                       |
+| ------------------------------------------------------------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `client.property_use.use_details.add_revision`               | `"matches a date that has already been provided"` | Revisions must be unique per `(propertyUseId, currentAsOf)`. Use a different date or call `update()`.       |
+
+### 404 subcases observed
+
+These all surface as `EpaPmApiError(status_code=404, error_number=404,
+errors=[EpaErrorDetail(error_number=404, error_description="…")])`.
+Branch on `status_code == 404` first; the descriptions are useful for
+logging but should not be parsed for control flow.
+
+| Triggering call                                                | `error_description`         |
+| -------------------------------------------------------------- | --------------------------- |
+| `client.property.get(invalid_id)`                              | `"Property does not exist."`|
+| `client.meter.get(invalid_id)`                                 | `"Meter does not exist."`   |
+| `client.report.get(invalid_id)`                                | `"Report not found."`       |
+| `client.account.custom_fields(invalid_id)`                     | `"Account does not exist."` |
+| `client.consumption_data.add(invalid_meter_id, …)`             | `"Meter does not exist."`   |
+| `client.consumption_data.get(invalid_meter_id, …)`             | `"Meter does not exist."`   |
+| `client.report.download(invalid_id)`                           | `"Report not found."`       |
+| `client.report.update(invalid_id, …)`                          | `"Report not found."`       |
+| `client.customer.get(invalid_id)`                              | *(empty `errorDescription` — `error_description` parses as `None`)* |
+| `client.property.energy_performance_project.get(invalid_id)`   | *(empty `errorDescription` — `error_description` parses as `None`)* |
+
+The two cases where `error_description` is empty are an EPA quirk: the
+`<error errorNumber="404" errorDescription=""/>` envelope is still well
+formed, but the description is a zero-length string and the wrapper
+exposes it as `None`. Don't write code that assumes the description is
+always populated.
+
+## Authentication errors
+
+EPA returns HTTP 401 with no XML envelope.
+
+
+
+`EpaPmAuthError` is raised on every `401` response. Two important
+shape details, confirmed by probing:
+
+1. The 401 body is **HTML** (a Tomcat-style status page), not the EPA
+   XML error envelope. `e.errors` will be `[]` and `e.error_number`
+   will be `None` — only `status_code` and `response_text` are useful.
+2. Don't loop on a wrong-password probe. The EPA test environment
+   shares its identity database with production and repeated 401s can
+   trigger account lockouts. One probe is plenty to confirm "creds
+   are wrong".
+
+The most common causes, in rough order of frequency:
+
+1. **Wrong environment.** Live and test have separate user databases.
+   A test username will not authenticate against the live counterpart
+   and vice versa — see [Authentication and account setup](usage.md#authentication-and-account-setup).
+2. **Credentials revoked or expired.** Confirm by logging in via the web UI.
+3. **Special characters not URL-encoded.** Should be a non-issue with the
+   wrapper (it passes the tuple to `httpx.Client(auth=...)`), but worth
+   ruling out for callers using a custom `http_client`.
+
+```python
+from epa_pm_api_wrapper.exceptions import EpaPmAuthError
+
+try:
+    client.account.get()
+except EpaPmAuthError:
+    # Wrong creds or wrong environment.
+    sys.exit("auth failed; check EPA_PM_USERNAME/PASSWORD and EPA_PM_TEST")
+```
+
+## Diagnosing the unknown
+
+If you hit a status code or `error_number` that's not in this page:
+
+1. **Check `e.response_text`** — the raw XML often includes a longer
+   English description beyond what fits in `error_description`.
+2. **Look at `e.status_code`** — `400` is almost always something in your
+   request payload; `403` is a permission/share issue; `404` is "doesn't
+   exist"; `5xx` is EPA-side.
+3. **Check the endpoint's EPA documentation** — every documented endpoint
+   lives at
+   `https://portfoliomanager.energystar.gov/webservices/home/api/<section>/<service>/<verb>`
+   and *sometimes* includes an Errors subsection.
+4. **Consult [the central error codes page](https://portfoliomanager.energystar.gov/webservices/home/errors)**
+   — only general HTTP statuses + `-100`/`-200` are listed there, but
+   it's still the canonical reference.
+5. **Enable DEBUG logging** on `epa_pm_api_wrapper.client` — outgoing
+   request `method`/`URL`/`params` are logged for every call. See
+   [Logging](usage.md#logging).
+
+If you reproduce a new `-200` description against a stable input and
+the table above doesn't cover it, a PR adding the row is welcome — see
+[Contributing](https://github.com/harryw1/EPA-PM-API-Wrapper/blob/main/CONTRIBUTING.md).

epa_pm_api_wrapper-0.4.0/docs/index.md

@@ -0,0 +1,46 @@
+# EPA PM API Wrapper
+
+Client wrapper for the EPA Portfolio Manager API.
+
+## Getting started
+
+- [Installation](installation.md) — how to install the wrapper.
+- [Usage](usage.md) — quickstart, authentication, error handling, retries, an end-to-end onboarding walkthrough, and worked examples for the most common workflows.
+- [Metrics](metrics.md) — metric-name catalog, runtime discovery, and which endpoint accepts which name.
+- [CLI](cli.md) — the bundled `epa_pm_api_wrapper` exploration tool.
+- [Errors](errors.md) — EPA error-number reference and how to branch on `EpaPmApiError`.
+- [API Reference](api.md) — auto-generated reference for every client method, exception, and resource.
+
+## What this library is
+
+A thin, typed client over the ENERGY STAR Portfolio Manager web services
+API. It signs requests with HTTP Basic Auth, serializes/deserializes the
+EPA's XML payloads to and from `xsdata`-generated dataclasses, retries
+transient transport errors, and exposes every published endpoint as a
+method on either `EpaPmClient` (sync) or `EpaPmAsyncClient` (async).
+
+## What this library is NOT
+
+A few intentional non-goals — knowing these saves time:
+
+- **Not a schema generator.** The `xsdata` dataclasses under
+  `epa_pm_api_wrapper.models` are pre-generated from the EPA's XSDs.
+  When EPA ships a new schema version you regenerate them from
+  `schemas/` per [`CONTRIBUTING.md`](https://github.com/harryw1/EPA-PM-API-Wrapper/blob/main/CONTRIBUTING.md);
+  the wrapper does not regenerate them at runtime.
+- **Not an auth broker.** EPA exposes only HTTP Basic Auth; the client
+  takes a username/password pair and forwards it. It does not refresh
+  tokens, manage sessions, or integrate with SSO.
+- **Not an async↔sync bridge.** `EpaPmClient` and `EpaPmAsyncClient`
+  are separate classes backed by `httpx.Client` and `httpx.AsyncClient`
+  respectively. Pick one for your runtime — the wrapper does not run
+  one inside the other.
+- **Not a metric-name validator.** Metric names passed to
+  `client.metrics.*` are sent verbatim to EPA, which validates them
+  server-side. See the [Metrics guide](metrics.md) for runtime
+  discovery via `client.report.metrics()`.
+- **Not a rate limiter.** The retry layer honors `Retry-After` and backs
+  off on 429, but it does not pre-throttle outgoing requests; if you're
+  fanning out concurrently you own the concurrency budget.
+- **Not a caching layer.** Every call hits EPA. Cache property/metric
+  reads in your application if your access pattern needs it.