python-eia 0.1.0__tar.gz → 0.2.1__tar.gz

python_eia-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

{python_eia-0.1.0 → python_eia-0.2.1}/.gitignore

@@ -4,4 +4,5 @@ docs
 __pycache__
 .ipynb_checkpoints
 data
-sketch
+sketch
+dist/

{python_eia-0.1.0 → python_eia-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-eia
-Version: 0.1.0
+Version: 0.2.1
 Summary: A Python client for the U.S. Energy Information Administration (EIA) API v2
 Project-URL: Homepage, https://github.com/datons/python-eia
 Project-URL: Repository, https://github.com/datons/python-eia.git
@@ -13,14 +13,16 @@ Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.7
+Requires-Python: >=3.10
+Requires-Dist: pandas>=2.0
 Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
 Requires-Dist: urllib3>=2.0.0
 Provides-Extra: dev
 Requires-Dist: black>=22.0; extra == 'dev'

python_eia-0.2.1/eia/.agents/skills/eia/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: eia
+description: Query U.S. energy data (EIA API v2). Use when the user asks about U.S. electricity, petroleum, natural gas, or coal data from the EIA.
+version: 1.0.0
+---
+
+# EIA Data Assistant
+
+You have access to the `python-eia` CLI and library for querying the U.S. Energy Information Administration (EIA) API v2.
+
+The EIA API is a **route-based tree**. You navigate routes to find data endpoints, then query them with facet filters and frequency options.
+
+## CLI Reference
+
+### Explore the API tree
+
+```bash
+# Top-level routes
+eia routes
+
+# Navigate deeper
+eia routes electricity
+eia routes electricity/rto
+eia routes electricity/rto/fuel-type-data  # Error if leaf — use 'eia meta' instead
+```
+
+### Inspect a data endpoint
+
+```bash
+# Show facets, frequencies, and data columns
+eia meta electricity/rto/fuel-type-data
+eia meta petroleum/pri/spt
+eia meta natural-gas/pri/sum
+```
+
+### List facet values
+
+```bash
+# List all values for a facet
+eia facets electricity/rto/fuel-type-data respondent
+eia facets electricity/rto/fuel-type-data fueltype
+eia facets petroleum/pri/spt series --format csv
+```
+
+### Fetch data
+
+```bash
+# Basic query
+eia get electricity/rto/fuel-type-data \
+  --start 2024-06-01 --end 2024-06-08 \
+  --frequency hourly \
+  --facet respondent=CISO \
+  --data value
+
+# Multiple facet values (repeat --facet)
+eia get electricity/retail-sales \
+  --start 2024-01-01 --end 2024-12-31 \
+  --facet stateid=CA --facet sectorid=RES --facet sectorid=COM \
+  --data revenue --data sales
+
+# Export to CSV
+eia get petroleum/pri/spt --start 2024-01-01 --end 2024-06-01 \
+  --format csv --output prices.csv
+
+# Sort
+eia get electricity/rto/fuel-type-data \
+  --start 2024-06-01 --end 2024-06-02 \
+  --frequency hourly --facet respondent=CISO --data value \
+  --sort period --sort-dir desc
+```
+
+### Fetch + eval pandas expression
+
+```bash
+# Descriptive stats
+eia exec electricity/rto/fuel-type-data \
+  --start 2024-06-01 --end 2024-06-08 \
+  --frequency hourly --facet respondent=CISO --data value \
+  -x "df.describe()"
+
+# Group by fuel type
+eia exec electricity/rto/fuel-type-data \
+  --start 2024-06-01 --end 2024-06-08 \
+  --frequency hourly --facet respondent=CISO --data value \
+  -x "df.groupby('fueltype')['value'].mean()"
+
+# Daily aggregation
+eia exec natural-gas/pri/sum \
+  --start 2024-01-01 --end 2024-06-01 \
+  -x "df.groupby('process')['value'].mean().sort_values(ascending=False)"
+```
+
+### Output options (all commands)
+
+```
+--format table|csv|json   (default: table)
+--output file.csv         (write to file instead of stdout)
+```
+
+## Common Routes
+
+| Route | Description |
+|-------|-------------|
+| `electricity/rto/fuel-type-data` | Real-time grid generation by fuel type |
+| `electricity/rto/region-data` | Real-time grid demand/generation by region |
+| `electricity/rto/interchange-data` | Real-time interchange between regions |
+| `electricity/retail-sales` | Retail electricity sales (monthly/annual) |
+| `electricity/electric-power-operational-data` | Power plant operational data |
+| `petroleum/pri/spt` | Spot petroleum prices (crude, gasoline, etc.) |
+| `petroleum/sum/sndw` | Weekly petroleum supply/demand |
+| `natural-gas/pri/sum` | Natural gas prices summary |
+| `natural-gas/sum/lsum` | Natural gas supply/demand summary |
+| `coal/shipments/receipts` | Coal shipments and receipts |
+| `total-energy/data` | Total energy overview (monthly/annual) |
+
+Use `eia routes` to discover more. Use `eia meta <route>` to see exact facets and frequencies.
+
+## Facet Conventions
+
+- **Format**: `--facet key=value` (repeatable)
+- **Multiple values**: repeat the flag — `--facet sectorid=RES --facet sectorid=COM`
+- **Common facets**: `respondent` (grid operator), `fueltype`, `stateid`, `sectorid`, `series`
+- Each endpoint has different facets — use `eia meta` and `eia facets` to discover them
+
+## Python Library
+
+```python
+from eia import EIAClient
+
+client = EIAClient()  # reads config file, then EIA_API_KEY env var
+
+# Navigate the route tree
+route = client.route("electricity/rto/fuel-type-data")
+route.routes          # Dict of child routes (if branch node)
+route.data            # Data object (if leaf node)
+
+# Inspect metadata
+route.data.facets              # FacetContainer with attribute access
+route.data.frequencies         # List[FrequencyInfo]
+route.data.data_columns        # Dict[str, DataColumnInfo]
+route.data.facets.respondent.get_values()  # List[FacetValue]
+
+# Direct access to a data endpoint
+data = client.get_data_endpoint("electricity/rto/fuel-type-data")
+
+# Fetch data as DataFrame
+df = data.get(
+    data_columns=["value"],
+    facets={"respondent": "CISO"},
+    frequency="hourly",
+    start="2024-01-01",
+    end="2024-01-31",
+    sort=[{"column": "period", "direction": "desc"}],
+)
+```
+
+## Configuration
+
+```bash
+# Store your API key persistently (recommended)
+eia config set api-key YOUR_KEY
+
+# Verify it's stored
+eia config get api-key
+```
+
+The config file is stored at `~/.config/eia/config.toml`.
+
+## Key Conventions
+
+- The `period` column is auto-converted to datetime (UTC for non-local frequencies)
+- The `value` column is auto-converted to numeric
+- Pagination is automatic by default (fetches all pages)
+- API key resolution: config file (`~/.config/eia/config.toml`) > `EIA_API_KEY` env var
+- API page limit is 5000 rows per request
+- Custom exception: `EIAError` (includes HTTP status code and API error code)

python_eia-0.2.1/eia/cli/__init__.py

@@ -0,0 +1,10 @@
+"""EIA CLI — command-line interface for the EIA API."""
+
+try:
+    from eia.cli.app import app
+except ImportError:
+    raise ImportError(
+        "CLI dependencies not installed. Install with: pip install python-eia"
+    )
+
+__all__ = ["app"]

python_eia-0.2.1/eia/cli/_output.py

@@ -0,0 +1,105 @@
+"""Shared output helpers for the EIA CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def render_dataframe(
+    df: pd.DataFrame,
+    format: str = "table",
+    output: str | None = None,
+    max_rows: int = 100,
+) -> None:
+    """Render a DataFrame in the requested format."""
+    if format == "csv":
+        text = df.to_csv(index=False)
+    elif format == "json":
+        text = df.to_json(orient="records", indent=2, date_format="iso")
+    else:
+        _print_rich_table(df, max_rows=max_rows)
+        return
+
+    if output:
+        Path(output).write_text(text)
+        typer.echo(f"Written to {output}")
+    else:
+        typer.echo(text)
+
+
+def render_result(
+    result: Any,
+    format: str = "table",
+    output: str | None = None,
+    max_rows: int = 100,
+) -> None:
+    """Render an eval result (DataFrame, Series, or scalar)."""
+    if isinstance(result, pd.Series):
+        result = result.to_frame()
+
+    if isinstance(result, pd.DataFrame):
+        if format == "csv":
+            text = result.to_csv()
+        elif format == "json":
+            text = result.to_json(orient="records", indent=2, date_format="iso")
+        else:
+            _print_rich_table(result, max_rows=max_rows, show_index=True)
+            return
+
+        if output:
+            Path(output).write_text(text)
+            typer.echo(f"Written to {output}")
+        else:
+            typer.echo(text)
+    else:
+        text = str(result)
+        if output:
+            Path(output).write_text(text)
+            typer.echo(f"Written to {output}")
+        else:
+            typer.echo(text)
+
+
+def _print_rich_table(
+    df: pd.DataFrame,
+    max_rows: int = 100,
+    show_index: bool = False,
+) -> None:
+    """Print a DataFrame as a Rich table."""
+    table = Table()
+
+    if show_index:
+        idx_name = str(df.index.name or "")
+        table.add_column(idx_name, style="cyan")
+
+    for col in df.columns:
+        table.add_column(str(col))
+
+    for idx, row in df.head(max_rows).iterrows():
+        values = []
+        if show_index:
+            values.append(str(idx))
+        values += [_fmt(row[c]) for c in df.columns]
+        table.add_row(*values)
+
+    if len(df) > max_rows:
+        table.caption = f"Showing {max_rows} of {len(df)} rows"
+
+    console.print(table)
+
+
+def _fmt(val: Any) -> str:
+    """Format a value for table display."""
+    if isinstance(val, float):
+        return f"{val:.4f}"
+    if val is None:
+        return ""
+    return str(val)

python_eia-0.2.1/eia/cli/app.py

@@ -0,0 +1,57 @@
+"""EIA CLI — main Typer application."""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+
+from eia.cli.config import get_api_key
+
+# Suppress the library's default INFO logging in CLI mode
+logging.getLogger().setLevel(logging.WARNING)
+
+app = typer.Typer(
+    name="eia",
+    help="CLI for the U.S. Energy Information Administration (EIA) API v2.",
+    no_args_is_help=True,
+)
+
+
+def get_client(api_key: str | None = None):
+    """Lazy import + construct client."""
+    from eia.client import EIAClient
+
+    resolved = api_key or get_api_key()
+    if not resolved:
+        typer.echo(
+            "Error: No API key. Set EIA_API_KEY or run: eia config set api-key <KEY>",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return EIAClient(api_key=resolved)
+
+
+# -- Register commands --------------------------------------------------------
+
+from eia.cli.routes_cmd import routes_command  # noqa: E402
+from eia.cli.meta_cmd import meta_command  # noqa: E402
+from eia.cli.facets_cmd import facets_command  # noqa: E402
+from eia.cli.get_cmd import get_command  # noqa: E402
+from eia.cli.exec_cmd import exec_command  # noqa: E402
+from eia.cli.config_cmd import config_app  # noqa: E402
+
+app.command(name="routes")(routes_command)
+app.command(name="meta")(meta_command)
+app.command(name="facets")(facets_command)
+app.command(name="get")(get_command)
+app.command(name="exec")(exec_command)
+app.add_typer(config_app, name="config", help="Configuration management")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

python_eia-0.2.1/eia/cli/config.py

@@ -0,0 +1,63 @@
+"""Configuration management — read/write config.toml and env vars."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".config" / "eia"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+
+def get_api_key() -> str | None:
+    """Resolve API key: config file > env var."""
+    # Try config file first
+    if CONFIG_FILE.exists():
+        try:
+            import tomllib
+        except ImportError:
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        with open(CONFIG_FILE, "rb") as f:
+            config = tomllib.load(f)
+        key = config.get("api-key")
+        if key:
+            return key
+
+    # Fall back to environment variable
+    return os.getenv("EIA_API_KEY")
+
+
+def set_config(key: str, value: str) -> None:
+    """Write a key-value pair to config.toml."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    config: dict = {}
+    if CONFIG_FILE.exists():
+        try:
+            import tomllib
+        except ImportError:
+            import tomli as tomllib  # type: ignore[no-redef]
+
+        with open(CONFIG_FILE, "rb") as f:
+            config = tomllib.load(f)
+
+    config[key] = value
+
+    # Write as simple TOML
+    lines = [f'{k} = "{v}"' for k, v in config.items()]
+    CONFIG_FILE.write_text("\n".join(lines) + "\n")
+
+
+def get_config(key: str) -> str | None:
+    """Read a value from config.toml."""
+    if not CONFIG_FILE.exists():
+        return None
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    with open(CONFIG_FILE, "rb") as f:
+        config = tomllib.load(f)
+    return config.get(key)

python_eia-0.2.1/eia/cli/config_cmd.py

@@ -0,0 +1,34 @@
+"""CLI subcommands for configuration management."""
+
+from __future__ import annotations
+
+import typer
+
+config_app = typer.Typer(no_args_is_help=True)
+
+
+@config_app.command("set")
+def config_set(
+    key: str = typer.Argument(..., help="Configuration key (e.g., 'api-key')"),
+    value: str = typer.Argument(..., help="Configuration value"),
+):
+    """Set a configuration value."""
+    from eia.cli.config import set_config
+
+    set_config(key, value)
+    typer.echo(f"Set {key} = {'***' if 'key' in key.lower() else value}")
+
+
+@config_app.command("get")
+def config_get(
+    key: str = typer.Argument(..., help="Configuration key to read"),
+):
+    """Get a configuration value."""
+    from eia.cli.config import get_config
+
+    val = get_config(key)
+    if val is None:
+        typer.echo(f"{key}: (not set)")
+    else:
+        display = "***" if "key" in key.lower() else val
+        typer.echo(f"{key} = {display}")

python_eia-0.2.1/eia/cli/exec_cmd.py

@@ -0,0 +1,78 @@
+"""CLI command: fetch data and evaluate a pandas expression."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from eia.cli._output import render_result
+from eia.cli.get_cmd import _parse_facets
+
+
+def exec_command(
+    route: str = typer.Argument(..., help="Route path to a data endpoint"),
+    start: Optional[str] = typer.Option(None, "--start", "-s", help="Start date (e.g. 2024-01-01)"),
+    end: Optional[str] = typer.Option(None, "--end", "-e", help="End date (e.g. 2024-01-31)"),
+    frequency: Optional[str] = typer.Option(None, "--frequency", help="Data frequency (e.g. hourly, monthly)"),
+    facet: Optional[list[str]] = typer.Option(None, "--facet", help="Facet filter as key=value (repeatable)"),
+    data: Optional[list[str]] = typer.Option(None, "--data", "-d", help="Data column to include (repeatable)"),
+    expr: str = typer.Option("df", "--expr", "-x", help="Python expression to evaluate (df, pd, np available)"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", "-k", help="EIA API key"),
+):
+    """Fetch data and evaluate a Python expression on it.
+
+    The fetched data is available as `df` (pandas DataFrame).
+    `pd` (pandas) and `np` (numpy) are also available.
+
+    \b
+    Examples:
+        eia exec electricity/rto/fuel-type-data \\
+          --start 2024-06-01 --end 2024-06-08 \\
+          --frequency hourly \\
+          --facet respondent=CISO --data value \\
+          -x "df.groupby('fueltype')['value'].mean()"
+
+        eia exec electricity/rto/fuel-type-data \\
+          --start 2024-06-01 --end 2024-06-03 \\
+          --frequency hourly \\
+          --facet respondent=CISO --data value \\
+          -x "df.describe()"
+    """
+    import numpy as np
+    import pandas as pd
+
+    from eia.cli.app import get_client
+
+    client = get_client(api_key)
+
+    # Build the Data object
+    data_endpoint = client.get_data_endpoint(route)
+
+    # Parse facets
+    facets = _parse_facets(facet) if facet else None
+
+    # Fetch
+    df = data_endpoint.get(
+        data_columns=data or None,
+        facets=facets,
+        frequency=frequency,
+        start=start,
+        end=end,
+    )
+
+    if df.empty:
+        typer.echo("No data returned.")
+        raise typer.Exit(0)
+
+    # Evaluate expression
+    namespace = {"df": df, "pd": pd, "np": np}
+    try:
+        result = eval(expr, {"__builtins__": {}}, namespace)  # noqa: S307
+    except Exception as exc:
+        typer.echo(f"Error evaluating expression: {exc}", err=True)
+        raise typer.Exit(1)
+
+    render_result(result, format=format, output=output)

python_eia-0.2.1/eia/cli/facets_cmd.py

@@ -0,0 +1,73 @@
+"""CLI command: list facet values for a data endpoint."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def facets_command(
+    route: str = typer.Argument(..., help="Route path to a data endpoint"),
+    facet_id: str = typer.Argument(..., help="Facet ID to list values for (e.g. 'respondent', 'fueltype')"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", "-k", help="EIA API key"),
+):
+    """List available values for a facet on a data endpoint.
+
+    \b
+    Examples:
+        eia facets electricity/rto/fuel-type-data respondent
+        eia facets electricity/rto/fuel-type-data fueltype --format csv
+    """
+    from eia.cli.app import get_client
+
+    client = get_client(api_key)
+
+    response = client.get_facet_values(route, facet_id)
+    facet_values = response.get("facets", [])
+
+    if not facet_values:
+        typer.echo(f"No values found for facet '{facet_id}' at '{route}'.")
+        raise typer.Exit(0)
+
+    if format == "json":
+        import json
+
+        text = json.dumps(facet_values, indent=2)
+        if output:
+            from pathlib import Path
+            Path(output).write_text(text)
+            typer.echo(f"Written to {output}")
+        else:
+            typer.echo(text)
+        return
+
+    if format == "csv":
+        lines = ["id,name"]
+        for v in facet_values:
+            name = (v.get("name") or "").replace(",", ";")
+            lines.append(f"{v['id']},{name}")
+        text = "\n".join(lines)
+        if output:
+            from pathlib import Path
+            Path(output).write_text(text)
+            typer.echo(f"Written to {output}")
+        else:
+            typer.echo(text)
+        return
+
+    # Rich table
+    table = Table(title=f"Facet: {facet_id}")
+    table.add_column("ID", style="cyan")
+    table.add_column("Name")
+
+    for v in facet_values:
+        table.add_row(v.get("id", ""), v.get("name", ""))
+
+    console.print(table)

python_eia-0.2.1/eia/cli/get_cmd.py

@@ -0,0 +1,89 @@
+"""CLI command: fetch data from a data endpoint."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from eia.cli._output import render_dataframe
+
+
+def _parse_facets(facet_args: list[str]) -> dict[str, str | list[str]]:
+    """Parse --facet key=value arguments into a dict.
+
+    Multiple values for the same key are collected into a list.
+    """
+    facets: dict[str, str | list[str]] = {}
+    for arg in facet_args:
+        if "=" not in arg:
+            typer.echo(f"Error: Invalid facet format '{arg}'. Use key=value.", err=True)
+            raise typer.Exit(1)
+        key, value = arg.split("=", 1)
+        if key in facets:
+            existing = facets[key]
+            if isinstance(existing, list):
+                existing.append(value)
+            else:
+                facets[key] = [existing, value]
+        else:
+            facets[key] = value
+    return facets
+
+
+def get_command(
+    route: str = typer.Argument(..., help="Route path to a data endpoint"),
+    start: Optional[str] = typer.Option(None, "--start", "-s", help="Start date (e.g. 2024-01-01)"),
+    end: Optional[str] = typer.Option(None, "--end", "-e", help="End date (e.g. 2024-01-31)"),
+    frequency: Optional[str] = typer.Option(None, "--frequency", help="Data frequency (e.g. hourly, monthly)"),
+    facet: Optional[list[str]] = typer.Option(None, "--facet", help="Facet filter as key=value (repeatable)"),
+    data: Optional[list[str]] = typer.Option(None, "--data", "-d", help="Data column to include (repeatable)"),
+    sort_col: Optional[str] = typer.Option(None, "--sort", help="Sort column"),
+    sort_dir: str = typer.Option("asc", "--sort-dir", help="Sort direction: asc or desc"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", "-k", help="EIA API key"),
+):
+    """Fetch data from an EIA data endpoint.
+
+    \b
+    Examples:
+        eia get electricity/rto/fuel-type-data \\
+          --start 2024-06-01 --end 2024-06-08 \\
+          --frequency hourly \\
+          --facet respondent=CISO \\
+          --data value
+
+        eia get petroleum/pri/spt --start 2024-01-01 --end 2024-06-01 \\
+          --format csv --output prices.csv
+    """
+    from eia.cli.app import get_client
+
+    client = get_client(api_key)
+
+    # Build the Data object
+    data_endpoint = client.get_data_endpoint(route)
+
+    # Parse facets
+    facets = _parse_facets(facet) if facet else None
+
+    # Sort
+    sort = None
+    if sort_col:
+        sort = [{"column": sort_col, "direction": sort_dir}]
+
+    # Fetch
+    df = data_endpoint.get(
+        data_columns=data or None,
+        facets=facets,
+        frequency=frequency,
+        start=start,
+        end=end,
+        sort=sort,
+    )
+
+    if df.empty:
+        typer.echo("No data returned.")
+        raise typer.Exit(0)
+
+    render_dataframe(df, format=format, output=output)

python_eia-0.2.1/eia/cli/meta_cmd.py

@@ -0,0 +1,92 @@
+"""CLI command: inspect a data endpoint's metadata."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+
+def meta_command(
+    route: str = typer.Argument(..., help="Route path to a data endpoint (e.g. 'electricity/rto/fuel-type-data')"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, json"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", "-k", help="EIA API key"),
+):
+    """Show facets, frequencies, and data columns for a data endpoint.
+
+    \b
+    Examples:
+        eia meta electricity/rto/fuel-type-data
+        eia meta petroleum/pri/spt --format json
+    """
+    from eia.cli.app import get_client
+
+    client = get_client(api_key)
+
+    metadata = client.get_metadata(route)
+
+    if "routes" in metadata and "facets" not in metadata:
+        typer.echo(f"'{route}' is not a data endpoint — it has child routes.")
+        typer.echo("Use 'eia routes' to explore, or navigate deeper.")
+        raise typer.Exit(1)
+
+    if format == "json":
+        import json
+
+        typer.echo(json.dumps(metadata, indent=2))
+        return
+
+    # --- Rich formatted output ---
+
+    name = metadata.get("name", route)
+    description = metadata.get("description", "")
+    start_period = metadata.get("startPeriod", "?")
+    end_period = metadata.get("endPeriod", "?")
+    default_freq = metadata.get("defaultFrequency", "?")
+
+    header = f"[bold]{name}[/bold]\n{description}\n\nPeriod: {start_period} → {end_period}  |  Default frequency: {default_freq}"
+    console.print(Panel(header, title=f"[cyan]{route}[/cyan]"))
+
+    # Frequencies
+    freqs = metadata.get("frequency", [])
+    if freqs:
+        freq_table = Table(title="Frequencies")
+        freq_table.add_column("ID", style="cyan")
+        freq_table.add_column("Description")
+        freq_table.add_column("Format")
+        for f in freqs:
+            if isinstance(f, dict):
+                freq_table.add_row(f.get("id", ""), f.get("description", ""), f.get("format", ""))
+        console.print(freq_table)
+
+    # Facets
+    facets = metadata.get("facets", [])
+    if facets:
+        facet_table = Table(title="Facets")
+        facet_table.add_column("ID", style="cyan")
+        facet_table.add_column("Description")
+        for fct in facets:
+            if isinstance(fct, dict):
+                facet_table.add_row(fct.get("id", ""), fct.get("description", ""))
+        console.print(facet_table)
+
+    # Data columns
+    data_cols = metadata.get("data", {})
+    if data_cols:
+        col_table = Table(title="Data Columns")
+        col_table.add_column("ID", style="cyan")
+        col_table.add_column("Alias")
+        col_table.add_column("Units")
+        for col_id, col_data in data_cols.items():
+            if isinstance(col_data, dict):
+                col_table.add_row(
+                    col_id,
+                    col_data.get("alias", ""),
+                    col_data.get("units", ""),
+                )
+        console.print(col_table)

python_eia-0.2.1/eia/cli/routes_cmd.py

@@ -0,0 +1,81 @@
+"""CLI command: explore API route tree."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def routes_command(
+    route: Optional[str] = typer.Argument(None, help="Route path (e.g. 'electricity' or 'electricity/rto')"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, csv, json"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", "-k", help="EIA API key"),
+):
+    """Explore the EIA API route tree.
+
+    \b
+    Examples:
+        eia routes                       # Top-level routes
+        eia routes electricity           # Child routes of electricity
+        eia routes electricity/rto       # Deeper navigation
+    """
+    from eia.cli.app import get_client
+
+    client = get_client(api_key)
+
+    slug = route or ""
+    metadata = client.get_metadata(slug)
+
+    routes_list = metadata.get("routes", [])
+    if not routes_list:
+        typer.echo(f"No child routes found at '{slug or '/'}'.")
+        if "data" in metadata or "facets" in metadata:
+            typer.echo("This is a data endpoint. Use 'eia meta' to inspect it.")
+        raise typer.Exit(0)
+
+    if format == "json":
+        import json
+
+        text = json.dumps(routes_list, indent=2)
+        if output:
+            from pathlib import Path
+            Path(output).write_text(text)
+            typer.echo(f"Written to {output}")
+        else:
+            typer.echo(text)
+        return
+
+    if format == "csv":
+        lines = ["id,name,description"]
+        for r in routes_list:
+            desc = (r.get("description") or "").replace(",", ";")
+            lines.append(f"{r['id']},{r.get('name', '')},{desc}")
+        text = "\n".join(lines)
+        if output:
+            from pathlib import Path
+            Path(output).write_text(text)
+            typer.echo(f"Written to {output}")
+        else:
+            typer.echo(text)
+        return
+
+    # Rich table
+    table = Table(title=f"Routes: {slug or '/'}")
+    table.add_column("ID", style="cyan")
+    table.add_column("Name")
+    table.add_column("Description")
+
+    for r in routes_list:
+        table.add_row(
+            r["id"],
+            r.get("name", ""),
+            r.get("description", ""),
+        )
+
+    console.print(table)

{python_eia-0.1.0 → python_eia-0.2.1}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-eia"
-version = "0.1.0"
+version = "0.2.1"
 description = "A Python client for the U.S. Energy Information Administration (EIA) API v2"
 readme = "README.md"
-requires-python = ">=3.7"
+requires-python = ">=3.10"
 license = "MIT"
 authors = [{ name = "Jesus Lopez", email = "jesus.lopez@datons.ai" }]
 classifiers = [
@@ -17,14 +17,16 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.7",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering",
 ]
-dependencies = ["requests>=2.31.0", "urllib3>=2.0.0"]
+dependencies = ["requests>=2.31.0", "urllib3>=2.0.0", "pandas>=2.0", "typer>=0.9", "rich>=13.0"]
+
+[project.scripts]
+eia = "eia.cli:app"
 
 [project.optional-dependencies]
 dev = [

python_eia-0.2.1/skills/eia/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: eia
+description: Query U.S. energy data (EIA API v2). Use when the user asks about U.S. electricity, petroleum, natural gas, or coal data from the EIA.
+version: 1.0.0
+---
+
+# EIA Data Assistant
+
+You have access to the `python-eia` CLI and library for querying the U.S. Energy Information Administration (EIA) API v2.
+
+The EIA API is a **route-based tree**. You navigate routes to find data endpoints, then query them with facet filters and frequency options.
+
+## CLI Reference
+
+### Explore the API tree
+
+```bash
+# Top-level routes
+eia routes
+
+# Navigate deeper
+eia routes electricity
+eia routes electricity/rto
+eia routes electricity/rto/fuel-type-data  # Error if leaf — use 'eia meta' instead
+```
+
+### Inspect a data endpoint
+
+```bash
+# Show facets, frequencies, and data columns
+eia meta electricity/rto/fuel-type-data
+eia meta petroleum/pri/spt
+eia meta natural-gas/pri/sum
+```
+
+### List facet values
+
+```bash
+# List all values for a facet
+eia facets electricity/rto/fuel-type-data respondent
+eia facets electricity/rto/fuel-type-data fueltype
+eia facets petroleum/pri/spt series --format csv
+```
+
+### Fetch data
+
+```bash
+# Basic query
+eia get electricity/rto/fuel-type-data \
+  --start 2024-06-01 --end 2024-06-08 \
+  --frequency hourly \
+  --facet respondent=CISO \
+  --data value
+
+# Multiple facet values (repeat --facet)
+eia get electricity/retail-sales \
+  --start 2024-01-01 --end 2024-12-31 \
+  --facet stateid=CA --facet sectorid=RES --facet sectorid=COM \
+  --data revenue --data sales
+
+# Export to CSV
+eia get petroleum/pri/spt --start 2024-01-01 --end 2024-06-01 \
+  --format csv --output prices.csv
+
+# Sort
+eia get electricity/rto/fuel-type-data \
+  --start 2024-06-01 --end 2024-06-02 \
+  --frequency hourly --facet respondent=CISO --data value \
+  --sort period --sort-dir desc
+```
+
+### Fetch + eval pandas expression
+
+```bash
+# Descriptive stats
+eia exec electricity/rto/fuel-type-data \
+  --start 2024-06-01 --end 2024-06-08 \
+  --frequency hourly --facet respondent=CISO --data value \
+  -x "df.describe()"
+
+# Group by fuel type
+eia exec electricity/rto/fuel-type-data \
+  --start 2024-06-01 --end 2024-06-08 \
+  --frequency hourly --facet respondent=CISO --data value \
+  -x "df.groupby('fueltype')['value'].mean()"
+
+# Daily aggregation
+eia exec natural-gas/pri/sum \
+  --start 2024-01-01 --end 2024-06-01 \
+  -x "df.groupby('process')['value'].mean().sort_values(ascending=False)"
+```
+
+### Output options (all commands)
+
+```
+--format table|csv|json   (default: table)
+--output file.csv         (write to file instead of stdout)
+```
+
+## Common Routes
+
+| Route | Description |
+|-------|-------------|
+| `electricity/rto/fuel-type-data` | Real-time grid generation by fuel type |
+| `electricity/rto/region-data` | Real-time grid demand/generation by region |
+| `electricity/rto/interchange-data` | Real-time interchange between regions |
+| `electricity/retail-sales` | Retail electricity sales (monthly/annual) |
+| `electricity/electric-power-operational-data` | Power plant operational data |
+| `petroleum/pri/spt` | Spot petroleum prices (crude, gasoline, etc.) |
+| `petroleum/sum/sndw` | Weekly petroleum supply/demand |
+| `natural-gas/pri/sum` | Natural gas prices summary |
+| `natural-gas/sum/lsum` | Natural gas supply/demand summary |
+| `coal/shipments/receipts` | Coal shipments and receipts |
+| `total-energy/data` | Total energy overview (monthly/annual) |
+
+Use `eia routes` to discover more. Use `eia meta <route>` to see exact facets and frequencies.
+
+## Facet Conventions
+
+- **Format**: `--facet key=value` (repeatable)
+- **Multiple values**: repeat the flag — `--facet sectorid=RES --facet sectorid=COM`
+- **Common facets**: `respondent` (grid operator), `fueltype`, `stateid`, `sectorid`, `series`
+- Each endpoint has different facets — use `eia meta` and `eia facets` to discover them
+
+## Python Library
+
+```python
+from eia import EIAClient
+
+client = EIAClient()  # reads config file, then EIA_API_KEY env var
+
+# Navigate the route tree
+route = client.route("electricity/rto/fuel-type-data")
+route.routes          # Dict of child routes (if branch node)
+route.data            # Data object (if leaf node)
+
+# Inspect metadata
+route.data.facets              # FacetContainer with attribute access
+route.data.frequencies         # List[FrequencyInfo]
+route.data.data_columns        # Dict[str, DataColumnInfo]
+route.data.facets.respondent.get_values()  # List[FacetValue]
+
+# Direct access to a data endpoint
+data = client.get_data_endpoint("electricity/rto/fuel-type-data")
+
+# Fetch data as DataFrame
+df = data.get(
+    data_columns=["value"],
+    facets={"respondent": "CISO"},
+    frequency="hourly",
+    start="2024-01-01",
+    end="2024-01-31",
+    sort=[{"column": "period", "direction": "desc"}],
+)
+```
+
+## Configuration
+
+```bash
+# Store your API key persistently (recommended)
+eia config set api-key YOUR_KEY
+
+# Verify it's stored
+eia config get api-key
+```
+
+The config file is stored at `~/.config/eia/config.toml`.
+
+## Key Conventions
+
+- The `period` column is auto-converted to datetime (UTC for non-local frequencies)
+- The `value` column is auto-converted to numeric
+- Pagination is automatic by default (fetches all pages)
+- API key resolution: config file (`~/.config/eia/config.toml`) > `EIA_API_KEY` env var
+- API page limit is 5000 rows per request
+- Custom exception: `EIAError` (includes HTTP status code and API error code)