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

{python_eia-0.2.1 → python_eia-0.3.0}/.github/workflows/publish.yml

@@ -1,14 +1,30 @@
-name: Publish to PyPI
+name: Release Please
 
 on:
   push:
     branches: [main]
 
+permissions:
+  contents: write
+  pull-requests: write
+
 jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
   publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
     runs-on: ubuntu-latest
     permissions:
-      id-token: write # Required for trusted publishing
+      id-token: write
     steps:
       - uses: actions/checkout@v4
 
@@ -24,5 +40,3 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          skip-existing: true

python_eia-0.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.0"
+}

python_eia-0.3.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.3.0](https://github.com/datons/python-eia/compare/python-eia-v0.2.1...python-eia-v0.3.0) (2026-03-04)
+
+
+### Features
+
+* add CLI, skill file, bump to 0.2.0, publish-on-push workflow ([b766f71](https://github.com/datons/python-eia/commit/b766f71a5eb08e4a6d2ddb77b38cb9f6a69f1bfa))
+* add data catalog, fix tz comparison and gap date formatting bugs ([f609aab](https://github.com/datons/python-eia/commit/f609aab23b7d0ac4ff01c38e7b1ede5be6c89476))
+* add full API schema caching to YAML catalog ([5947cf1](https://github.com/datons/python-eia/commit/5947cf121dc61c960e3887669b768d103752fcf0))
+* add parquet cache for offline-first data access ([5f7338b](https://github.com/datons/python-eia/commit/5f7338bb0533cc3a197df6514d996b85c460d639))
+
+
+### Bug Fixes
+
+* correct author email to datons.com ([d62f40d](https://github.com/datons/python-eia/commit/d62f40d3569cee661251bb93d627dbb664a88c81))

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

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: python-eia
-Version: 0.2.1
+Version: 0.3.0
 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
+Project-URL: Repository, https://github.com/datons/python-eia
 Project-URL: Issues, https://github.com/datons/python-eia/issues
-Author-email: Jesus Lopez <jesus.lopez@datons.ai>
+Project-URL: Changelog, https://github.com/datons/python-eia/releases
+Author-email: Jesús López <jesus.lopez@datons.com>
 License-Expression: MIT
+Keywords: api,eia,electricity,energy,gas,oil,usa
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -20,6 +22,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.31.0
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.9

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

@@ -4,12 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-eia"
-version = "0.2.1"
+version = "0.3.0"
 description = "A Python client for the U.S. Energy Information Administration (EIA) API v2"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
-authors = [{ name = "Jesus Lopez", email = "jesus.lopez@datons.ai" }]
+authors = [{ name = "Jesús López", email = "jesus.lopez@datons.com" }]
+keywords = ["eia", "energy", "electricity", "oil", "gas", "api", "usa"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -23,7 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering",
 ]
-dependencies = ["requests>=2.31.0", "urllib3>=2.0.0", "pandas>=2.0", "typer>=0.9", "rich>=13.0"]
+dependencies = ["requests>=2.31.0", "urllib3>=2.0.0", "pandas>=2.0", "pyarrow>=14.0", "typer>=0.9", "rich>=13.0", "pyyaml>=6.0"]
 
 [project.scripts]
 eia = "eia.cli:app"
@@ -41,8 +42,15 @@ dev = [
 
 [project.urls]
 Homepage = "https://github.com/datons/python-eia"
-Repository = "https://github.com/datons/python-eia.git"
+Repository = "https://github.com/datons/python-eia"
 Issues = "https://github.com/datons/python-eia/issues"
+Changelog = "https://github.com/datons/python-eia/releases"
 
 [tool.hatch.build.targets.wheel]
-packages = ["eia"]
+packages = ["src/eia"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: tests that hit real APIs (deselect with -m 'not integration')",
+]

python_eia-0.3.0/release-please-config.json

@@ -0,0 +1,19 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "python-eia",
+      "extra-files": [
+        "pyproject.toml"
+      ],
+      "changelog-sections": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "perf", "section": "Performance" },
+        { "type": "docs", "section": "Documentation", "hidden": true },
+        { "type": "chore", "section": "Miscellaneous", "hidden": true }
+      ]
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

python_eia-0.3.0/src/eia/.agents/skills/eia/SKILL.md

@@ -0,0 +1,172 @@
+---
+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: 2.0.0
+---
+
+# EIA Data Assistant
+
+You have access to the `python-eia` library and CLI for querying the U.S. Energy Information Administration (EIA) API v2.
+
+## When to use what
+
+- **Python scripts** (default): reproducible, composable, saveable. Use for any data work the user will want to keep or iterate on.
+- **CLI**: quick one-shot lookups, exploration, sanity checks. Use when the user wants a fast answer they won't need again.
+- **If unsure**: ask the user whether they want a script or a quick CLI check.
+
+## Built-in Catalog (OFFLINE — no API calls)
+
+The library ships with a YAML catalog containing full API schema for curated routes: columns, frequencies, periods, and **all facet values**. Always check the catalog first to avoid unnecessary API calls.
+
+### Cataloged Routes
+
+| Route | Description | Frequency |
+|-------|-------------|-----------|
+| `electricity/rto/fuel-type-data` | Real-time grid generation by fuel type | hourly |
+| `electricity/rto/region-data` | Real-time grid demand/generation by region | hourly |
+| `electricity/rto/interchange-data` | Real-time interchange between regions | hourly |
+| `electricity/retail-sales` | Retail electricity sales by state/sector | monthly |
+| `petroleum/pri/spt` | Spot petroleum prices (crude, gasoline, etc.) | daily |
+| `natural-gas/pri/sum` | Natural gas prices summary | monthly |
+| `natural-gas/move/expc` | US natural gas exports by country | monthly |
+| `natural-gas/move/impc` | US natural gas imports by country | monthly |
+| `total-energy/data` | Total energy overview (production, consumption, etc.) | monthly |
+
+For routes **not** in the catalog, use `eia routes` (CLI) to discover and `eia meta` to inspect.
+
+## Python Library (default)
+
+```python
+from eia import EIAClient
+
+client = EIAClient()  # reads config file, then EIA_API_KEY env var
+
+# --- Catalog access (offline, no API calls) ---
+
+# Get endpoint with cached schema — no API metadata call
+data = client.get_data_endpoint("electricity/rto/fuel-type-data")
+
+# Inspect metadata (all cached for cataloged routes)
+data.facets                    # FacetContainer with attribute access
+data.frequencies               # List[FrequencyInfo]
+data.data_columns              # Dict[str, DataColumnInfo]
+data.start_period              # "2019-01-01T00"
+data.end_period                # "2026-03-04T07"
+
+# Facet values — cached, no API call
+respondents = data.facets.respondent.get_values()
+# [FacetValue(id='CISO', name='California ISO'), ...]
+
+fuel_types = data.facets.fueltype.get_values()
+# [FacetValue(id='SUN', name='Solar'), ...]
+
+# Or access catalog directly
+from eia.catalog import get_route, list_routes
+route = get_route("electricity/rto/fuel-type-data")
+route.data_columns   # (DataColumn(id='value', units='megawatthours', ...),)
+route.frequencies     # (Frequency(id='hourly', ...), Frequency(id='local-hourly', ...))
+route.facets[0].values  # {'CISO': 'California ISO', 'PJM': 'PJM Interconnection LLC', ...}
+
+# --- Fetch data (hits API) ---
+
+df = data.get(
+    data_columns=["value"],
+    facets={"respondent": "CISO"},
+    frequency="hourly",
+    start="2024-01-01",
+    end="2024-01-31",
+    sort=[{"column": "period", "direction": "desc"}],
+)
+
+# Multiple facet values
+df = data.get(
+    data_columns=["revenue", "sales"],
+    facets={"stateid": "CA", "sectorid": ["RES", "COM"]},
+    frequency="monthly",
+    start="2024-01-01",
+    end="2024-12-31",
+)
+
+# --- Route tree navigation (for discovery — hits API) ---
+route = client.route("electricity/rto/fuel-type-data")
+route.routes          # Dict of child routes (if branch node)
+route.data            # Data object (if leaf node)
+```
+
+### Facet conventions
+
+- **Common facets**: `respondent` (grid operator), `fueltype`, `stateid`, `sectorid`, `series`
+- **Multiple values**: pass a list — `facets={"sectorid": ["RES", "COM"]}`
+- **Prefer catalog** for facet discovery: `get_route().facets[i].values` has all valid values offline
+
+### 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 page limit is 5000 rows per request
+- Custom exception: `EIAError` (includes HTTP status code and API error code)
+
+## CLI Reference (quick lookups)
+
+### Catalog (offline)
+
+```bash
+eia catalog routes                              # List all cataloged routes
+eia catalog show electricity/rto/fuel-type-data # Full details (columns, frequencies, facet values)
+eia catalog recipes                             # Pre-configured query recipes
+eia catalog recipe lng-exports-europe           # Show a specific recipe
+eia catalog refresh --apply                     # Refresh schema from API
+```
+
+### Explore (hits API)
+
+```bash
+eia routes                                      # Top-level routes
+eia routes electricity/rto                      # Navigate deeper
+eia meta electricity/rto/fuel-type-data         # Endpoint metadata
+eia facets electricity/rto/fuel-type-data respondent  # Facet values
+```
+
+### Fetch data
+
+```bash
+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
+eia get petroleum/pri/spt --start 2024-01-01 --end 2024-06-01 \
+  --format csv --output prices.csv
+```
+
+### Exec (ad-hoc pandas)
+
+```bash
+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()"
+```
+
+### Output options
+
+```
+--format table|csv|json   (default: table)
+--output file.csv         (write to file instead of stdout)
+```
+
+## Configuration
+
+```bash
+eia config set api-key YOUR_KEY    # Store API key
+eia config get api-key             # Verify
+```
+
+Config file: `~/.config/eia/config.toml`. API key resolution: config file > `EIA_API_KEY` env var.

{python_eia-0.2.1 → python_eia-0.3.0/src}/eia/__init__.py

@@ -5,6 +5,8 @@ A Python client for interacting with the U.S. Energy Information Administration
 """
 
 from .client import EIAClient, EIAError
+from .cache import CacheConfig
+from . import catalog
 
 __version__ = "0.1.0"
-__all__ = ["EIAClient", "EIAError"]
+__all__ = ["EIAClient", "EIAError", "CacheConfig", "catalog"]