Metadata-Version: 2.5
Name: ordinex-energy
Version: 0.2.0
Summary: Python client for the Ordinex Energy Intelligence API
Project-URL: Homepage, https://energy.ordinexdata.com
Project-URL: Documentation, https://energy.ordinexdata.com/docs
Project-URL: Source, https://github.com/svandam1988/energy-market-DaaS/tree/main/clients/python
Author: OrdinexData
License: Proprietary - see https://energy.ordinexdata.com/terms
Keywords: EIA,ERCOT,api-client,backtesting,energy,factors,point-in-time
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# ordinex-energy

A thin Python client for the [Ordinex Energy Intelligence API](https://energy.ordinexdata.com) -
point-in-time-safe, walk-forward-validated energy market factors over
one REST API.

## Install

```bash
pip install ordinex-energy          # core client
pip install ordinex-energy[pandas]  # + pandas DataFrame support
```

If the PyPI release is not available yet, install it directly from this
repo:

```bash
pip install "git+https://github.com/svandam1988/energy-market-DaaS.git#subdirectory=clients/python"
```

## Quickstart

```python
from ordinex_energy import OrdinexEnergyClient

client = OrdinexEnergyClient(api_key="your-api-key")

# A validated factor, as a plain list of dicts
rows = client.factors(factor="storage_percentile", subject="NW2_EPG0_SWO_R48_BCF")

# ...or as a pandas DataFrame (requires the [pandas] extra)
df = client.factors(factor="wti_brent_spread", as_dataframe=True)

# Cross-sectional snapshots
client.factors_latest(factor="ercot_spark_spread")
client.rankings("storage_percentile", order="desc", limit=5)
client.screen("ercot_spark_spread", min_value=-50, max_value=0)

# Raw series - automatically paginated, you always get the full result
wti = client.series(series_id="RWTC", as_dataframe=True)

# ENTSO-E (EU) raw series
client.eu_capacity(in_domain_eic="10Y1001A1001A82H", out_domain_eic="10YDK-1--------W")

# What a factor is backed by, and how much confidence the evidence supports
client.factor_metadata(factor="storage_percentile")
client.factor_regimes("ercot_spark_spread")

# Your own usage
client.usage()
```

## Bulk point-in-time export

Backtests should not page through thousands of requests. `export_factors`
streams a whole date-bounded slice in one call. Every row has `period`
(the date it describes) and `known_at` (the earliest date it could have
been known, period plus the factor's reporting lag).

```python
# Everything knowable on 2025-06-30, as a DataFrame
df = client.export_factors(factor="ercot_spark_spread", as_of="2025-06-30", as_dataframe=True)

# Walk-forward without leakage: cut folds on known_at, not period
full = client.export_factors(factor="storage_percentile", as_dataframe=True)
train = full[full["known_at"] <= "2024-12-31"]

# Very large exports: write straight to disk
client.export_factors(start_date="2023-01-01", path="factors.csv")
```

Notes: values are not revision-versioned (point-in-time here means
publication timing, not "the value as first published"); a request
matching more than 1,000,000 rows is refused with a 422 asking you to
narrow it; only public factors and servable subjects are exported.

## Pagination

`/v1/series`, `/v1/factors`, and the `/v1/eu/*` routes are paginated by
the API itself (`limit`/`offset`, capped at 5000 rows/page) to bound
response size. This client handles that transparently - every method
above returns the *complete* matching result as one Python list (or
DataFrame); you never need to loop over pages yourself.

## Errors

A non-2xx response raises `OrdinexEnergyAPIError`, with `.status_code`
and `.detail` set from the real response:

```python
from ordinex_energy import OrdinexEnergyAPIError

try:
    client.factors_latest(factor="not-a-real-factor")
except OrdinexEnergyAPIError as exc:
    print(exc.status_code, exc.detail)  # 404 "factor 'not-a-real-factor' not found"
```

A `429` (rate limit) is retried automatically (honoring the server's
`Retry-After` header) up to `max_retries` times (default 3) before
raising.

## Development

```bash
pip install -e .[dev,pandas]
pytest
```
