[ENG-3072] Add Optional Return Formats (Python, Pandas, Polars)

[WillKoehrsen]

• Add support for more return formats in the GridStatus API client, allowing users to choose between Python lists of dicts, Pandas DataFrames, and Polars DataFrames
• pandas is a required dependency (installed by default), polars is an optional dependency
  • The library uses lazy loading, so advanced users can still use return_format="python" without pandas being imported
• return_format can be specified once when instantiating the GridStatusClient or per API call

Verification

• Run full test suite: make test
  • Tests are parameterized where appropriate for all three return formats

Testing Different Installed Packages

• The following work through the different options for installing packages and the resulting available return_format options
• First export $(grep GRIDSTATUS_API_KEY .env | xargs) assuming your API key is in .env

Standard Install (pandas included)

# Create venv with standard install
uv venv .venv-standard
uv pip install -e . --python .venv-standard/bin/python

# Test: should default to pandas format
.venv-standard/bin/python -c "
from gridstatusio import GridStatusClient
client = GridStatusClient()
print(f'Default format: {client.return_format}')
data = client.get_dataset('isone_fuel_mix', limit=3, verbose=False)
print(f'Type: {type(data)}')
"

# Test: python format should work
.venv-standard/bin/python -c "
from gridstatusio import GridStatusClient
client = GridStatusClient(return_format='python')
data = client.get_dataset('isone_fuel_mix', limit=3, verbose=False)
print(f'Type: {type(data)}')
print(data[0])
"

# Test: requesting polars should raise MissingDependencyError
.venv-standard/bin/python -c "
from gridstatusio import GridStatusClient
client = GridStatusClient(return_format='polars')
"

# Cleanup
rm -rf .venv-standard

Full Install (pandas and polars)

# Create venv with all dependencies
uv venv .venv-all
uv pip install -e ".[all]" --python .venv-all/bin/python

# Test: should default to pandas format
.venv-all/bin/python -c "
from gridstatusio import GridStatusClient
client = GridStatusClient()
print(f'Default format: {client.return_format}')
"

# Test: all formats should work
.venv-all/bin/python -c "
from gridstatusio import GridStatusClient

client = GridStatusClient()

pandas_data = client.get_dataset('isone_fuel_mix', limit=3, return_format='pandas', verbose=False)
print(f'Pandas: {type(pandas_data)}')

polars_data = client.get_dataset('isone_fuel_mix', limit=3, return_format='polars', verbose=False)
print(f'Polars: {type(polars_data)}')

python_data = client.get_dataset('isone_fuel_mix', limit=3, return_format='python', verbose=False)
print(f'Python: {type(python_data)}')
"

# Cleanup
rm -rf .venv-all

Minimal Install Without Pandas (Advanced)

# Create venv with minimal install (no pandas)
uv venv .venv-minimal
uv pip install -e . --no-deps --python .venv-minimal/bin/python
uv pip install requests tqdm termcolor tabulate urllib3 setuptools idna certifi virtualenv ipykernel plotly --python .venv-minimal/bin/python

# Test: verify pandas is not imported on module load
.venv-minimal/bin/python -c "
import sys
import gridstatusio
print(f'pandas loaded: {\"pandas\" in sys.modules}')
"

# Test: should default to python format when pandas unavailable
.venv-minimal/bin/python -c "
from gridstatusio import GridStatusClient
client = GridStatusClient(return_format='python')
print(f'Format: {client.return_format}')
data = client.get_dataset('isone_fuel_mix', limit=3, verbose=False)
print(f'Type: {type(data)}')
print(data[0])
"

# Test: requesting pandas should raise MissingDependencyError
.venv-minimal/bin/python -c "
from gridstatusio import GridStatusClient
client = GridStatusClient(return_format='pandas')
"

# Cleanup
rm -rf .venv-minimal

[WillKoehrsen]

This PR has been updated so that pandas is still in the required packages but technically the library can be used without pandas (see instructions in README). It still adds Python and polars return types.

[WillKoehrsen]

I re-ran all the notebooks to ensure they work with these updates. We can undo these changes.