Metadata-Version: 2.4
Name: radaroptions
Version: 0.1.0
Summary: DuckDB-based reader for an options-chain data lake stored in Azure Data Lake Storage
Author-email: David Santamaria <contactdsantamaria@gmail.com>
License: Proprietary - All Rights Reserved
License-File: LICENSE
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: duckdb>=1.1.3
Requires-Dist: pandas>=2.2
Requires-Dist: python-dotenv>=1.0
Requires-Dist: typer>=0.15
Description-Content-Type: text/markdown

# radaroptions

DuckDB-based reader for an options-chain data lake stored in Azure Data Lake
Storage Gen2. No JVM, no Spark cluster required - reads partitioned parquet
directly via DuckDB's `azure` extension.

Auth is picked automatically based on which environment variable is set:

- **A read-only SAS URL** (`RADAR_LAKE_SAS_URL`) - the normal way to get
  access. One single value someone gives you (bundles account + container +
  token) - no Azure account needed at all.
- **`credential_chain`** - an Azure CLI session (`az login`) or a service
  principal (`AZURE_TENANT_ID` / `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET`),
  for anyone with their own Azure AD identity that has read access to the
  storage account (set `RADAR_LAKE_ACCOUNT` / `RADAR_LAKE_CONTAINER` too in
  this case, since there's no URL to derive them from).

## Install

```bash
pip install radaroptions
```

## Configure

Installing the package doesn't grant you access. **No access yet? Email
dsantamaria@radaroptions.net.**

```
RADAR_LAKE_SAS_URL=<the URL they give you>
```

That's the only variable most people need. Running a read without it set
fails with a clear message pointing back to this contact.

## Usage

### Python

```python
from radaroptions import read_day, read_range

df = read_day("2026-06-11")

df = read_range(
    "2026-01-01", "2026-06-30",
    columns=["strike", "option_type", "open_interest", "gamma", "current_price", "time"],
)
```

### CLI

```bash
radaroptions read-day 2026-06-11 --out day.parquet
radaroptions read-range 2026-01-01 2026-06-30 -c strike,option_type,open_interest
radaroptions query "SELECT count(*) FROM read_parquet('abfss://<container>@<account>.dfs.core.windows.net/2026/06/*/*.parquet')"
```

`read_range` globs one file pattern per (year, month) covering the requested
dates and filters on the data's own `time` column, using `union_by_name=true`
so columns added or renamed over the years don't break the read.

## Troubleshooting

- **TLS / proxy errors on Windows**: set `RADAR_LAKE_AZURE_TRANSPORT=curl` to
  switch DuckDB's azure extension from WinHTTP to curl.
- **Schema errors reading a date range**: a genuine type change in the
  underlying data (e.g. a column that used to be `decimal` and is now
  `double`) can still error even with `union_by_name=true` - pass
  `columns=[...]` to select only the fields you need.

## License

Proprietary - see `LICENSE`. Installable for authorized use only; no rights
are granted to copy, modify, or redistribute this software.
