feat: add CLI, skill file, bump to 0.2.0, publish-on-push workflow

- CLI with typer for terminal access to EIA data
- Claude Code skill file for AI-assisted usage
- Bump version to 0.2.0
- Add push-to-main PyPI publish workflow with skip-existing

Author: jsulopzs

.github/workflows/publish.yml

@@ -24,3 +24,5 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

.gitignore

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

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"]

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)

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()

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)

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}")

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)