Switch to OEDI Format

.github/workflows/testing.yml

@@ -11,13 +11,16 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.12', '3.13', '3.14']
     name: Tests - Python ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
         with:
-         python-version: ${{ matrix.python-version}}
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
       - name: Configure AWS Credentials
         uses: aws-actions/configure-aws-credentials@v4.1.0
         with:
@@ -29,8 +32,8 @@ jobs:
       - name: Who am I?
         run: aws sts get-caller-identity
       - name: Install buildstock_query
-        run: pip install -e .[dev]
+        run: uv sync --group dev --python ${{ matrix.python-version }}
       - name: Pytest
-        run: python -m pytest -vv
+        run: uv run --python ${{ matrix.python-version }} pytest -vv
       - name: Lint
-        run: flake8 buildstock_query
+        run: uv run --python ${{ matrix.python-version }} flake8 buildstock_query

.gitignore

@@ -14,7 +14,23 @@ poetry.lock
 build/
 *.egg-info
 *.parquet
+# Track snapshot-cache parquets so the data-check survives a fresh clone.
+!tests/query_snapshots/**/*.parquet
+!tests/query_snapshots/**/*.sql
+!tests/query_snapshots/**/*.json
 *.txt
 *.csv
 *.yml
 .bsq_cache
+# Transient query-execution audit log written by query_core; not snapshot data.
+.execution_history
+# Per-session SqlCache hash log — populated by SqlCache.get/put, consumed by
+# tests/cleanup_stale_caches.py to identify orphaned cache entries.
+.cache_usage_log
+# Per-session record_query JSONL log — populated by tests/snapshot_recorder.py,
+# consumed by tests/normalize_invariant_snapshot.py to update from_invariants.json.
+.from_invariants_log.jsonl
+# Local-only test cache: full metadata parquets downloaded from S3 (~hundreds
+# of MB) for pure-pandas methods like get_applied_options. Tests that use this
+# cache require --include-local; default behavior is to skip them in CI.
+tests/local_only/cache/

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format

.python-version

@@ -0,0 +1 @@
+3.12

buildstock_query/__init__.py

@@ -3,31 +3,27 @@
 - - - - - - - - -
 A library to run AWS Athena queries to get various data from a BuildStock run. The main class is called BuildStockQuery.
 An object of BuildStockQuery needs to be created to perform various queries. In addition to supporting various
-query member functions, the BuildStockQuery object contains 4 member objects that can be used to perform certain
-class of queries and analysis. These 4 member objects can be accessed as follows::
+query member functions, the BuildStockQuery object contains 3 member objects that can be used to perform certain
+class of queries and analysis. These member objects can be accessed as follows::
 
-bsq = BuildStockQuery(...)  `BuildStockQuery` object  
-bsq.agg  `buildstock_query.aggregate_query.BuildStockAggregate`  
-bsq.report  `buildstock_query.report_query.BuildStockReport`  
-bsq.savings  `buildstock_query.savings_query.BuildStockSavings`  
-bsq.utility  `buildstock_query.utility_query.BuildStockUtility`  
+bsq = BuildStockQuery(...)  `BuildStockQuery` object
+bsq.agg  `buildstock_query.aggregate_query.BuildStockAggregate`
+bsq.report  `buildstock_query.report_query.BuildStockReport`
+bsq.utility  `buildstock_query.utility_query.BuildStockUtility`
 
 ```
-# Some basic query can be done directly using the BuildStockQuery object. For example:
-from buildstock_query import BuildStockQuery 
+# The core query API lives on the BuildStockQuery object itself:
+from buildstock_query import BuildStockQuery
 bsq = BuildStockQuery(...)
 bsq.get_results_csv()
 bsq.get_upgrades_csv()
+bsq.query(enduses=[...], annual_only=True, ...)                 # annual baseline / upgrade results
+bsq.query(enduses=[...], annual_only=False, ...)                # timeseries aggregations
+bsq.query(enduses=[...], upgrade_id="1", include_savings=True)  # savings shape
 
-# Other more specific queries can be done using specific query class objects. For example:
-bsq.agg.aggregate_annual(...)
-bsq.agg.aggregate_timeseries(...)
-...
+# Reports and utility-specific helpers:
 bsq.report.get_success_report(...)
 bsq.report.get_successful_simulation_count(...)
-...
-bsq.savings.savings_shape(...)
-...
 bsq.utility.aggregate_annual_by_eiaid(...)
 ```