How yudiell/energy-apis works
Project Type and Purpose
• This is a small Python‐based CLI tool (“eia-api”) that wraps the U.S. Energy Information Administration (EIA) REST API v2.
• Its purpose is to fetch specific data endpoints (e.g. crude-oil-imports, electric-power-operational-data), apply any default parameters, and present results to the user.
File‐Structure Analysis
• Top level:
• pyproject.toml – Poetry configuration, dependencies, and defines the CLI entrypoint.
• energy_apis/ – root Python package.
• tests/ – unit or integration tests.
• postman/ – Postman collection for API calls (external testing/integration).
• energy_apis/eia/api/v2/
• __main__.py – CLI engine; entrypoint for poetry run eia-api.
• flow.py – orchestrates calls to the HTTP client and handles request parameters.
• No database or frontend. All I/O is HTTP to remote EIA API and console output.
Key Components
a. CLI Layer
• Component: “eia-api CLI”
• Technology: Python entrypoint (__main__.py), invoked via Poetry.
• Responsibility: Parse --environment and --request flags; kick off the flow.
b. Core Library Layer
• Component: energy_apis.eia.api.v2.flow
• Responsibility: Build the HTTP request with default parameters (API key, endpoint name), invoke the HTTP Client.
c. HTTP Client / Adapter
• Component: (e.g.) Requests library or built-in HTTP client
• Responsibility: GET/POST to https://api.eia.gov/v2/{endpoint}
d. External Service
• Component: EIA API v2 (REST endpoint)
• External dependency; returns JSON data.
• Component: postman/collections/EIA APIv2.postman_collection.json
• Responsibility: Manual or automated testing of endpoints outside of the CLI.
f. Tests
• Component: tests/*.py
• Responsibility: Unit tests for flow logic and CLI parsing.
Relationships and Data Flows
• CLI → Flow module: passes parsed flags →
• Flow module → HTTP Client: issues REST call →
• HTTP Client → External EIA API: fetches JSON →
• External API → HTTP Client → Flow module: returns data →
• Flow module → CLI: prints or stores results → end user
• Tests exercise Flow module and CLI in isolation (mocking HTTP client).
• Postman connects to External API directly for exploratory testing.
Architectural Patterns & Design Principles
• Layered Architecture:
• Presentation (CLI)
• Business Logic (flow.py)
• Infrastructure (HTTP client)
• Single Responsibility per module.
• Dependency Injection (injecting environment and request parameters).
• Externalize configuration via Poetry and environment flags.