EPA-PM-API-Wrapper 0.3.0__py3-none-any.whl

epa_pm_api_wrapper/__init__.py

@@ -0,0 +1,30 @@
+"""Top-level package for EPA PM API Wrapper."""
+
+from epa_pm_api_wrapper.client import EpaPmAsyncClient, EpaPmClient
+from epa_pm_api_wrapper.exceptions import (
+    EpaErrorDetail,
+    EpaPmApiError,
+    EpaPmAuthError,
+    EpaPmError,
+)
+from epa_pm_api_wrapper.models import (
+    AcceptRejectType,
+    MeterConsumption,
+    MeterData,
+    SharingResponse,
+)
+from epa_pm_api_wrapper.retry import RetryConfig
+
+__all__ = [
+    "AcceptRejectType",
+    "EpaErrorDetail",
+    "EpaPmApiError",
+    "EpaPmAsyncClient",
+    "EpaPmAuthError",
+    "EpaPmClient",
+    "EpaPmError",
+    "MeterConsumption",
+    "MeterData",
+    "RetryConfig",
+    "SharingResponse",
+]

epa_pm_api_wrapper/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

epa_pm_api_wrapper/cli.py

@@ -0,0 +1,413 @@
+"""Console script for epa_pm_api_wrapper.
+
+The CLI is intentionally a thin exploration tool — read-only commands for
+the most common ad-hoc lookups (accounts, properties, meters, consumption,
+catalogs). For programmatic use of the full ~70-endpoint surface, instantiate
+:class:`EpaPmClient` directly.
+
+Each command takes ``--username`` / ``--password`` / ``--test`` (with matching
+``EPA_PM_USERNAME`` / ``EPA_PM_PASSWORD`` / ``EPA_PM_TEST`` environment
+variables, also picked up from a `.env` file in the working directory).
+"""
+
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.table import Table
+
+from epa_pm_api_wrapper.client import EpaPmClient
+
+# Load environment variables from .env file
+load_dotenv()
+
+app = typer.Typer()
+console = Console()
+
+
+def _client(username: str, password: str, test: bool) -> EpaPmClient:
+    return EpaPmClient(username=username, password=password, use_test_env=test)
+
+
+_USERNAME = typer.Option(..., envvar="EPA_PM_USERNAME", help="EPA PM Username")
+_PASSWORD = typer.Option(..., envvar="EPA_PM_PASSWORD", help="EPA PM Password", hide_input=True)
+_TEST = typer.Option(False, "--test", envvar="EPA_PM_TEST", help="Use test environment")
+
+
+@app.command()
+def account(
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """Get account details."""
+    client = _client(username, password, test)
+    try:
+        acc = client.account.get()
+        console.print("[bold green]Account Details:[/bold green]")
+        console.print(f"ID: {acc.id}")
+        console.print(f"Username: {acc.username}")
+        console.print(f"Organization: {acc.organization.name}")
+        console.print(f"Primary Business: {acc.organization.primary_business}")
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-properties")
+def list_properties(
+    account_id: int = typer.Argument(..., help="Account ID to list properties for"),
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List all properties accessible under an account."""
+    client = _client(username, password, test)
+    try:
+        response = client.property.list(account_id)
+        if not response.links or not response.links.link:
+            console.print("[yellow]No properties found.[/yellow]")
+            return
+        table = Table(title=f"Properties for account {account_id}")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name")
+        for link in response.links.link:
+            table.add_row(str(link.id), link.hint or "")
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("get-property")
+def get_property(
+    property_id: int,
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """Get property details."""
+    client = _client(username, password, test)
+    try:
+        prop = client.property.get(property_id)
+        console.print("[bold green]Property Details:[/bold green]")
+        console.print(f"ID: {property_id}")
+        console.print(f"Name: {prop.name}")
+        console.print(f"Primary Function: {prop.primary_function}")
+        if prop.address:
+            addr = prop.address
+            console.print(f"Address: {addr.address1}, {addr.city}, {addr.state} {addr.postal_code}")
+        else:
+            console.print("Address: N/A")
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-meters")
+def list_meters(
+    property_id: int = typer.Argument(..., help="Property ID to list meters for"),
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List meters on a property."""
+    client = _client(username, password, test)
+    try:
+        response = client.meter.list(property_id)
+        if not response.links or not response.links.link:
+            console.print("[yellow]No meters found.[/yellow]")
+            return
+        table = Table(title=f"Meters for property {property_id}")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name")
+        for link in response.links.link:
+            table.add_row(str(link.id), link.hint or "")
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("get-meter")
+def get_meter(
+    meter_id: int,
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """Get meter details."""
+    client = _client(username, password, test)
+    try:
+        meter = client.meter.get(meter_id)
+        console.print("[bold green]Meter Details:[/bold green]")
+        console.print(f"ID: {meter.id}")
+        console.print(f"Name: {meter.name}")
+        console.print(f"Type: {meter.type_value}")
+        console.print(f"Unit: {meter.unit_of_measure}")
+        console.print(f"Metered: {meter.metered}")
+        console.print(f"In Use: {meter.in_use}")
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("get-consumption")
+def get_consumption(
+    meter_id: int,
+    page: int = typer.Option(1, help="1-based page number (120 records per page)"),
+    start_date: str | None = typer.Option(None, help="ISO 8601 start date (YYYY-MM-DD)"),
+    end_date: str | None = typer.Option(None, help="ISO 8601 end date (YYYY-MM-DD)"),
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """Get consumption records for a meter."""
+    client = _client(username, password, test)
+    try:
+        data = client.consumption_data.get(meter_id, page=page, start_date=start_date, end_date=end_date)
+        records = data.meter_consumption or []
+        if not records:
+            console.print("[yellow]No consumption records in range.[/yellow]")
+            return
+        table = Table(title=f"Consumption for meter {meter_id} (page {page})")
+        table.add_column("ID", style="cyan")
+        table.add_column("Start Date")
+        table.add_column("End Date")
+        table.add_column("Usage", justify="right")
+        table.add_column("Estimated", justify="center")
+        for rec in records:
+            table.add_row(
+                str(rec.id),
+                str(rec.start_date) if rec.start_date else "",
+                str(rec.end_date) if rec.end_date else "",
+                str(rec.usage) if rec.usage is not None else "",
+                "yes" if rec.estimated_value else "no",
+            )
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-customers")
+def list_customers(
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List customers connected to your account."""
+    client = _client(username, password, test)
+    try:
+        response = client.customer.list()
+        if not response.links or not response.links.link:
+            console.print("[yellow]No connected customers.[/yellow]")
+            return
+        table = Table(title="Connected customers")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name / Hint")
+        for link in response.links.link:
+            table.add_row(str(link.id), link.hint or "")
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-pending-shares")
+def list_pending_shares(
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List pending property and meter share requests."""
+    client = _client(username, password, test)
+    try:
+        prop_pending = client.share.pending_property_shares()
+        meter_pending = client.share.pending_meter_shares()
+        conn_pending = client.share.pending_connections()
+
+        console.print(f"[bold]Pending property shares:[/bold] {len(prop_pending.property)}")
+        console.print(f"[bold]Pending meter shares:[/bold] {len(meter_pending.meter)}")
+        console.print(f"[bold]Pending account connections:[/bold] {len(conn_pending.account)}")
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-property-uses")
+def list_property_uses(
+    property_id: int = typer.Argument(..., help="Property ID to list property uses for"),
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List property uses defined for a property."""
+    client = _client(username, password, test)
+    try:
+        response = client.property_use.list(property_id)
+        if not response.links or not response.links.link:
+            console.print("[yellow]No property uses found.[/yellow]")
+            return
+        table = Table(title=f"Property uses for property {property_id}")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name / Hint")
+        for link in response.links.link:
+            table.add_row(str(link.id), link.hint or "")
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-buildings")
+def list_buildings(
+    property_id: int = typer.Argument(..., help="Property ID to list buildings for"),
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List buildings under a property."""
+    client = _client(username, password, test)
+    try:
+        response = client.building.list(property_id)
+        if not response.links or not response.links.link:
+            console.print("[yellow]No buildings found.[/yellow]")
+            return
+        table = Table(title=f"Buildings for property {property_id}")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name / Hint")
+        for link in response.links.link:
+            table.add_row(str(link.id), link.hint or "")
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-edu")
+def list_edu(
+    property_id: int = typer.Argument(..., help="Property ID to list available EDUs for"),
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List available Electric Distribution Utilities for a property."""
+    client = _client(username, password, test)
+    try:
+        edus = client.property.edu.list(property_id)
+        if not edus.edu:
+            console.print("[yellow]No EDUs available.[/yellow]")
+            return
+        table = Table(title=f"EDUs available for property {property_id}")
+        table.add_column("Code", style="cyan")
+        table.add_column("Name")
+        table.add_column("Preferred")
+        table.add_column("Selected")
+        for edu in edus.edu:
+            table.add_row(
+                edu.edu_code or "",
+                edu.name or "",
+                "yes" if edu.preferred else "no",
+                "yes" if edu.selected else "no",
+            )
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-federal-agencies")
+def list_federal_agencies(
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List federal agencies (catalog)."""
+    client = _client(username, password, test)
+    try:
+        catalog = client.property.federal_agency.list()
+        if not catalog.agency:
+            console.print("[yellow]No agencies in catalog.[/yellow]")
+            return
+        table = Table(title="Federal agencies")
+        table.add_column("ID", style="cyan")
+        table.add_column("Code")
+        table.add_column("Name")
+        table.add_column("Country")
+        for agency in catalog.agency:
+            table.add_row(
+                str(agency.id) if agency.id else "",
+                agency.code or "",
+                agency.name or "",
+                str(agency.country) if agency.country else "",
+            )
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-egrid-subregions")
+def list_egrid_subregions(
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List eGrid subregions (catalog)."""
+    client = _client(username, password, test)
+    try:
+        catalog = client.property.e_grid_subregion.list()
+        if not catalog.e_grid_subregion:
+            console.print("[yellow]No subregions in catalog.[/yellow]")
+            return
+        table = Table(title="eGrid subregions")
+        table.add_column("Code", style="cyan")
+        table.add_column("Name")
+        table.add_column("Country")
+        for sr in catalog.e_grid_subregion:
+            table.add_row(
+                sr.code or "",
+                sr.name or "",
+                str(sr.country) if sr.country else "",
+            )
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-reports")
+def list_reports(
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List reports in your account."""
+    client = _client(username, password, test)
+    try:
+        response = client.report.list()
+        if not response.links or not response.links.link:
+            console.print("[yellow]No reports found.[/yellow]")
+            return
+        table = Table(title="Reports")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name / Hint")
+        for link in response.links.link:
+            table.add_row(str(link.id), link.hint or "")
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+@app.command("list-report-templates")
+def list_report_templates(
+    username: str = _USERNAME,
+    password: str = _PASSWORD,
+    test: bool = _TEST,
+) -> None:
+    """List report templates available to your account."""
+    client = _client(username, password, test)
+    try:
+        response = client.report.templates.list()
+        if not response.links or not response.links.link:
+            console.print("[yellow]No templates found.[/yellow]")
+            return
+        table = Table(title="Report templates")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name / Hint")
+        for link in response.links.link:
+            table.add_row(str(link.id), link.hint or "")
+        console.print(table)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+if __name__ == "__main__":
+    app()