Metadata-Version: 2.4
Name: EPA-PM-API-Wrapper
Version: 0.3.4
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
Project-URL: documentation, https://harryw1.github.io/EPA-PM-API-Wrapper/
Project-URL: homepage, https://github.com/harryw1/EPA-PM-API-Wrapper
Author-email: Harrison Weiss <haweiss@dcas.nyc.gov>
Maintainer-email: Harrison Weiss <haweiss@dcas.nyc.gov>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Requires-Dist: xsdata>=26.2
Description-Content-Type: text/markdown

# EPA PM API Wrapper

[![PyPI version](https://img.shields.io/pypi/v/EPA-PM-API-Wrapper.svg)](https://pypi.org/project/EPA-PM-API-Wrapper/)
[![CI](https://github.com/harryw1/EPA-PM-API-Wrapper/actions/workflows/ci.yml/badge.svg)](https://github.com/harryw1/EPA-PM-API-Wrapper/actions/workflows/ci.yml)
[![Python versions](https://img.shields.io/pypi/pyversions/EPA-PM-API-Wrapper.svg)](https://pypi.org/project/EPA-PM-API-Wrapper/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Client wrapper for the EPA Portfolio Manager API.

* [GitHub](https://github.com/harryw1/EPA-PM-API-Wrapper/) | [PyPI](https://pypi.org/project/EPA-PM-API-Wrapper/) | [Documentation](https://harryw1.github.io/EPA-PM-API-Wrapper/)
* Created by [Harrison Weiss](https://publicpresence.org) | GitHub [@harryw1](https://github.com/harryw1) | PyPI [@harryw1](https://pypi.org/user/harryw1/)
* MIT License

## Features

*   **Full API coverage:** Every public endpoint in the ENERGY STAR Portfolio Manager web services API is bound — account, property, propertyUse, building, meter, consumption, waste, reporting, target finder, HEY, and the various catalogs (federal agencies, eGrid, weather stations, EDU/PGP).
*   **Sync and async clients:** `EpaPmClient` and `EpaPmAsyncClient` share the same resource-namespaced surface; pick whichever fits your runtime.
*   **Typed XML models:** Request and response payloads are dataclasses generated from the EPA XSDs (via `xsdata`), so IDE autocomplete and type checkers work out of the box.
*   **Structured error handling:** `EpaPmApiError` carries `status_code`, a parsed `errors` list, and an `error_number` accessor for branching without regexing the message; `EpaPmAuthError` covers 401s.
*   **Production-ready transport:** Configurable timeout/transport/`httpx.Client` injection, context-manager lifecycle, and built-in retry/backoff for 429 + 5xx + connection-level errors with `Retry-After` support.
*   **Pagination iterators:** `client.consumption_data.iter(meter_id)` and `client.waste_data.iter(meter_id)` walk pages internally.
*   **Live and test environments:** Switch between production and `wstest` with a single flag.
*   **CLI included:** A `typer`-based CLI (`epa_pm_api_wrapper`) for ad-hoc lookups across the most common resources.

## Usage

The CLI will prompt for credentials or read them from environment variables.

### Environment Variables

You can set the following environment variables:

*   `EPA_PM_USERNAME`
*   `EPA_PM_PASSWORD`
*   `EPA_PM_TEST`: Set to `true` to target the test environment instead of live.

### Using a `.env` file

Copy the example file and fill in your credentials:

```bash
cp .env.example .env
# Edit .env with your credentials
```

The CLI will automatically detect and load this file.

## Documentation

Documentation is built with [Zensical](https://zensical.org/) and deployed to GitHub Pages.

* **Live site:** https://harryw1.github.io/EPA-PM-API-Wrapper/
* **Preview locally:** `just docs-serve` (serves at http://localhost:8000)
* **Build:** `just docs-build`

API documentation is auto-generated from docstrings using [mkdocstrings](https://mkdocstrings.github.io/).

Docs deploy automatically on push to `main` via GitHub Actions. To enable this, go to your repo's Settings > Pages and set the source to **GitHub Actions**.

## Development

To set up for local development:

```bash
# Clone your fork
git clone git@github.com:your_username/EPA-PM-API-Wrapper.git
cd EPA-PM-API-Wrapper

# Install in editable mode with live updates
uv tool install --editable .
```

This installs the CLI globally but with live updates - any changes you make to the source code are immediately available when you run `epa_pm_api_wrapper`.

Run tests:

```bash
uv run pytest
```

Run quality checks (format, lint, type check, test):

```bash
just qa
```

## Versioning

This project follows [Semantic Versioning](https://semver.org/). The public
API is everything exported from `epa_pm_api_wrapper.__all__` plus the
attribute-namespaced resource methods on `EpaPmClient` / `EpaPmAsyncClient`.
Anything in a private module (leading underscore) or the internal
`_request` / `_arequest` plumbing is implementation detail and may change
in any release.

Pin to a compatible release range when depending on this library:

```
EPA-PM-API-Wrapper>=0.3,<0.4
```

## Author

EPA PM API Wrapper was created in 2026 by Harrison Weiss.

Built with [Cookiecutter](https://github.com/cookiecutter/cookiecutter) and the [audreyfeldroy/cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage) project template.
