Metadata-Version: 2.4
Name: cftc-cot-soda
Version: 0.2.0
Summary: Python SDK for CFTC Commitments of Traders data
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.23
Requires-Dist: sodapy>=2.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: cache
Requires-Dist: diskcache>=5.0; extra == "cache"
Dynamic: license-file

# CFTC COT SDK

[![PyPI](https://img.shields.io/pypi/v/cftc-cot.svg)](https://pypi.org/project/cftc-cot/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A robust, verified Python SDK for accessing, querying, and analyzing [CFTC Commitments of Traders (COT)](https://publicreporting.cftc.gov/stories/s/r4w3-av2u) data.

## Overview

The `cftc-cot` SDK provides a fluent, production-ready interface for the CFTC's SODA2 API. It simplifies the complexity of querying 6 different CFTC datasets, handles API-specific naming quirks, and provides powerful post-fetch analysis tools.

## Key Features

- **Fluent API**: Chainable query building for intuitive data retrieval.
- **Production-Tested**: Verified field mappings and API interactions against live CFTC data.
- **Advanced Analysis**: Net Positions, Z-Scores, the classic 0–100 **COT Index**, extreme positioning detection, long/short ratios, percentile ranks, and week-over-week change.
- **Caching**: Optional in-memory or persistent disk caching of API responses (COT data updates weekly, so a 24h TTL eliminates redundant requests).
- **Resilient Networking**: Automatic retry with exponential backoff on transient API failures (429/5xx).
- **Command-Line Interface**: A `cftc-cot` CLI for quick lookups without writing Python.
- **Robust Field Handling**: Preserves official API quirks (typos, naming inconsistencies) using structured field constants.
- **Production Ready**: Full type hinting, comprehensive exception hierarchy, and rate-limiting support via app tokens.

## Installation

```bash
pip install cftc-cot-soda

# With disk caching support:
pip install cftc-cot-soda[cache]
```

## Quick Start

```python
from cftc_cot import COTClient, COTAnalysis

# Initialize client
client = COTClient()

# Query: 52-week history of Crude Oil positioning
df = client.legacy().market("Crude Oil").last_n_weeks(52).execute()

# Analyze: Compute net positions and the COT Index
analysis = COTAnalysis(df, classification="legacy")
df_analyzed = analysis.cot_index(window=52)

print(df_analyzed[['report_date_as_yyyy_mm_dd', 'noncomm_net', 'noncomm_net_cot_index']].tail())
```

### Caching

```python
# In-memory cache (per-process) or persistent disk cache.
client = COTClient(cache="memory")
client = COTClient(cache="disk", cache_dir="./cot_cache", cache_ttl=86400)
```

### Command-Line Interface

```bash
cftc-cot latest  --dataset legacy --market "Crude Oil"
cftc-cot history --dataset legacy --market "Crude Oil" --weeks 52
cftc-cot markets --dataset legacy
cftc-cot index   --dataset legacy --market "Crude Oil" --window 156

# Choose output format and enable caching:
cftc-cot --format json --cache memory latest --dataset legacy --market "Gold"
```

## Documentation

For a complete API reference, guides, and dataset specifications, please visit our **[GitHub Wiki](https://github.com/victorKariuki/cftc-cot/wiki)**.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
