Metadata-Version: 2.4
Name: oilpriceapi
Version: 1.4.0
Summary: Official Python SDK for OilPriceAPI - Real-time and historical oil prices
Author-email: OilPriceAPI <support@oilpriceapi.com>
Maintainer-email: OilPriceAPI Team <support@oilpriceapi.com>
License: MIT License
        
        Copyright (c) 2025 OilPriceAPI
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://oilpriceapi.com
Project-URL: Documentation, https://docs.oilpriceapi.com/sdk/python
Project-URL: Repository, https://github.com/oilpriceapi/python-sdk
Project-URL: Issues, https://github.com/oilpriceapi/python-sdk/issues
Project-URL: Changelog, https://github.com/oilpriceapi/python-sdk/blob/main/CHANGELOG.md
Keywords: oil,prices,api,commodities,energy,brent,wti,natural gas,trading,finance
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: typing-extensions>=4.5.0; python_version < "3.10"
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == "pandas"
Requires-Dist: numpy>=1.20.0; extra == "pandas"
Provides-Extra: async
Requires-Dist: aiohttp>=3.8.0; extra == "async"
Provides-Extra: cache
Requires-Dist: redis>=4.5.0; extra == "cache"
Requires-Dist: cachetools>=5.3.0; extra == "cache"
Provides-Extra: cli
Requires-Dist: click>=8.0.0; extra == "cli"
Requires-Dist: rich>=13.0.0; extra == "cli"
Provides-Extra: all
Requires-Dist: oilpriceapi[async,cache,cli,pandas]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.0.261; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

# OilPriceAPI Python SDK

> **Real-time oil and commodity price data for Python** - Professional-grade API at 98% less cost than Bloomberg Terminal

[![PyPI version](https://badge.fury.io/py/oilpriceapi.svg)](https://badge.fury.io/py/oilpriceapi)
[![PyPI Downloads](https://img.shields.io/pypi/dm/oilpriceapi)](https://pypistats.org/packages/oilpriceapi)
[![Python](https://img.shields.io/pypi/pyversions/oilpriceapi.svg)](https://pypi.org/project/oilpriceapi/)
[![Tests](https://github.com/oilpriceapi/python-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/oilpriceapi/python-sdk/actions/workflows/test.yml)
[![Coverage](https://codecov.io/gh/oilpriceapi/python-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/oilpriceapi/python-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**[Get Free API Key](https://oilpriceapi.com/auth/signup)** • **[Documentation](https://docs.oilpriceapi.com/sdk/python)** • **[Examples](EXAMPLES.md)** • **[Pricing](https://oilpriceapi.com/pricing)**

The official Python SDK for [OilPriceAPI](https://oilpriceapi.com) - Real-time and historical oil prices for Brent Crude, WTI, Natural Gas, and more.

**Quick start:**
```bash
pip install oilpriceapi
```

## 🚀 Quick Start

### Installation

```bash
pip install oilpriceapi
```

### Basic Usage

```python
from oilpriceapi import OilPriceAPI

# Initialize client (uses OILPRICEAPI_KEY env var by default)
client = OilPriceAPI()

# Get latest Brent Crude price
brent = client.prices.get("BRENT_CRUDE_USD")
print(f"Brent Crude: ${brent.value:.2f}")
# Output: Brent Crude: $71.45

# Get multiple prices
prices = client.prices.get_multiple(["BRENT_CRUDE_USD", "WTI_USD", "NATURAL_GAS_USD"])
for price in prices:
    print(f"{price.commodity}: ${price.value:.2f}")
```

### Historical Data with Pandas

```python
# Get historical data as DataFrame
df = client.prices.to_dataframe(
    commodity="BRENT_CRUDE_USD",
    start="2024-01-01",
    end="2024-12-31",
    interval="daily"
)

# Add technical indicators
df = client.analysis.with_indicators(
    df,
    indicators=["sma_20", "sma_50", "rsi", "bollinger_bands"]
)

# Calculate spread between Brent and WTI
spread = client.analysis.spread("BRENT_CRUDE_USD", "WTI_USD", start="2024-01-01")
```

### Diesel Prices (New in v1.3.0)

```python
# Get state average diesel price (free tier)
ca_price = client.diesel.get_price("CA")
print(f"California diesel: ${ca_price.price:.2f}/gallon")
print(f"Source: {ca_price.source}")
print(f"Updated: {ca_price.updated_at}")

# Get nearby diesel stations (paid tiers)
result = client.diesel.get_stations(
    lat=37.7749,   # San Francisco
    lng=-122.4194,
    radius=8047    # 5 miles in meters
)

print(f"Regional average: ${result.regional_average.price:.2f}/gallon")
print(f"Found {len(result.stations)} stations")

# Find cheapest station
cheapest = min(result.stations, key=lambda s: s.diesel_price)
print(f"Cheapest: {cheapest.name} at {cheapest.formatted_price}")
print(f"Savings: ${abs(cheapest.price_delta):.2f}/gal vs average")

# Get diesel prices as DataFrame
df = client.diesel.to_dataframe(states=["CA", "TX", "NY", "FL"])
print(df[["state", "price", "updated_at"]])

# Station data as DataFrame
df_stations = client.diesel.to_dataframe(
    lat=34.0522,   # Los Angeles
    lng=-118.2437,
    radius=5000
)
print(df_stations[["name", "diesel_price", "price_vs_average"]])
```

### Price Alerts (New in v1.4.0)

```python
# Create a price alert with webhook notification
alert = client.alerts.create(
    name="Brent High Alert",
    commodity_code="BRENT_CRUDE_USD",
    condition_operator="greater_than",
    condition_value=85.00,
    webhook_url="https://your-server.com/webhook",  # Optional
    enabled=True,
    cooldown_minutes=60  # Min time between triggers
)

print(f"Alert created: {alert.id}")
print(f"Monitoring: {alert.commodity_code}")
print(f"Condition: {alert.condition_operator} ${alert.condition_value}")

# List all alerts
alerts = client.alerts.list()
for alert in alerts:
    print(f"{alert.name}: {alert.enabled} ({alert.trigger_count} triggers)")

# Update an alert
updated = client.alerts.update(
    alert.id,
    condition_value=90.00,
    enabled=False
)

# Test webhook endpoint
test_result = client.alerts.test_webhook("https://your-server.com/webhook")
if test_result.success:
    print(f"Webhook OK: {test_result.status_code} in {test_result.response_time_ms}ms")
else:
    print(f"Webhook failed: {test_result.error}")

# Delete an alert
client.alerts.delete(alert.id)

# Get alerts as DataFrame
df = client.alerts.to_dataframe()
print(df[["name", "commodity_code", "condition_value", "trigger_count"]])
```

**Supported operators:**
- `greater_than` - Price exceeds threshold
- `less_than` - Price falls below threshold
- `equals` - Price matches threshold
- `greater_than_or_equal` - Price meets or exceeds threshold
- `less_than_or_equal` - Price meets or falls below threshold

**Webhook Payload:**
```json
{
  "alert_id": "550e8400-e29b-41d4-a716-446655440000",
  "alert_name": "Brent High Alert",
  "commodity_code": "BRENT_CRUDE_USD",
  "current_price": 86.50,
  "condition_operator": "greater_than",
  "condition_value": 85.00,
  "triggered_at": "2025-12-15T10:30:00Z"
}
```

## 📊 Features

- ✅ **Simple API** - Intuitive methods for all endpoints
- ✅ **Type Safe** - Full type hints for IDE autocomplete
- ✅ **Pandas Integration** - First-class DataFrame support
- ✅ **Price Alerts** - Automated monitoring with webhook notifications 🔔 NEW
- ✅ **Diesel Prices** - State averages + station-level pricing ⛽
- ✅ **Async Support** - High-performance async client
- ✅ **Smart Caching** - Reduce API calls automatically
- ✅ **Rate Limit Handling** - Automatic retries with backoff
- ✅ **Technical Indicators** - Built-in SMA, RSI, MACD, etc.
- ✅ **CLI Tool** - Command-line interface included

## 📚 Documentation

**[Complete SDK Documentation →](docs/index.md)** | **[Online Docs →](https://docs.oilpriceapi.com/sdk/python)**

### Authentication

```python
# Method 1: Environment variable (recommended)
export OILPRICEAPI_KEY="your_api_key"
client = OilPriceAPI()

# Method 2: Direct initialization
client = OilPriceAPI(api_key="your_api_key")

# Method 3: With configuration
client = OilPriceAPI(
    api_key="your_api_key",
    timeout=30,
    max_retries=3,
    cache="memory",
    cache_ttl=300
)
```

### Available Commodities

- `BRENT_CRUDE_USD` - Brent Crude Oil
- `WTI_USD` - West Texas Intermediate
- `NATURAL_GAS_USD` - Natural Gas
- `DIESEL_USD` - Diesel
- `GASOLINE_USD` - Gasoline
- `HEATING_OIL_USD` - Heating Oil
- [View all commodities](https://docs.oilpriceapi.com/commodities)

### Error Handling

```python
from oilpriceapi.exceptions import OilPriceAPIError, RateLimitError, DataNotFoundError

try:
    price = client.prices.get("INVALID_CODE")
except DataNotFoundError as e:
    print(f"Commodity not found: {e}")
except RateLimitError as e:
    print(f"Rate limited. Resets in {e.seconds_until_reset}s")
except OilPriceAPIError as e:
    print(f"API error: {e}")
```

## ⚡ Async Support

```python
import asyncio
from oilpriceapi import AsyncOilPriceAPI

async def get_prices():
    async with AsyncOilPriceAPI() as client:
        prices = await asyncio.gather(
            client.prices.get("BRENT_CRUDE_USD"),
            client.prices.get("WTI_USD"),
            client.prices.get("NATURAL_GAS_USD")
        )
        return prices

# Run async function
prices = asyncio.run(get_prices())
```

## 🛠️ CLI Tool

```bash
# Get current price
oilprice get BRENT_CRUDE_USD

# Export historical data
oilprice export WTI_USD --start 2024-01-01 --format csv -o wti_2024.csv

# Watch prices in real-time
oilprice watch BRENT_CRUDE_USD --interval 60
```

## 🧪 Testing

The SDK includes utilities for testing your applications:

```python
from oilpriceapi.testing import MockClient

def test_my_strategy():
    client = MockClient()
    client.set_price("BRENT_CRUDE_USD", 75.50)

    result = my_trading_strategy(client)
    assert result.action == "BUY"
```

## 📈 Examples

### Real-World Use Cases

See **[EXAMPLES.md](https://github.com/OilpriceAPI/python-sdk/blob/main/EXAMPLES.md)** for comprehensive examples including:
- 📊 **Trading Strategies** - Moving averages, spread analysis, risk management
- 📈 **Data Analysis** - Seasonal patterns, correlations, forecasting
- 💻 **Web Applications** - Dashboards, REST APIs, monitoring systems
- 📤 **Data Export** - Excel reports, database integration, alerts

### Code Samples

Check out the [examples/](https://github.com/OilpriceAPI/python-sdk/tree/main/examples/) directory for:
- [Quickstart Notebook](examples/quickstart.ipynb)
- [Data Analysis](examples/data_analysis.ipynb)
- [Trading Signals](examples/trading_signals.ipynb)
- [Async Operations](examples/async_example.py)

## 🔧 Development

```bash
# Clone repository
git clone https://github.com/oilpriceapi/python-sdk
cd python-sdk

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .

# Type checking
mypy oilpriceapi
```

## 📝 License

MIT License - see [LICENSE](https://github.com/OilpriceAPI/python-sdk/blob/main/LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guide](https://github.com/OilpriceAPI/python-sdk/blob/main/CONTRIBUTING.md) for details.

## 💬 Support

- 📧 Email: support@oilpriceapi.com
- 🐛 Issues: [GitHub Issues](https://github.com/oilpriceapi/python-sdk/issues)
- 📖 Docs: [Documentation](https://docs.oilpriceapi.com/sdk/python)

## 🔗 Links

- [OilPriceAPI Website](https://oilpriceapi.com)
- [API Documentation](https://docs.oilpriceapi.com)
- [Pricing](https://oilpriceapi.com/pricing)
- [Status Page](https://status.oilpriceapi.com)

---

## 🌟 Why OilPriceAPI?

[OilPriceAPI](https://oilpriceapi.com) provides professional-grade commodity price data at **98% less cost than Bloomberg Terminal** ($24,000/year vs $45/month). Trusted by energy traders, financial analysts, and developers worldwide.

### Key Benefits
- ⚡ **Real-time data** updated every 5 minutes
- 📊 **Historical data** for trend analysis and backtesting
- 🔒 **99.9% uptime** with enterprise-grade reliability
- 🚀 **5-minute integration** with this Python SDK
- 💰 **Free tier** with 100 requests (lifetime) to get started

**[Start Free →](https://oilpriceapi.com/auth/signup)** | **[View Pricing →](https://oilpriceapi.com/pricing)** | **[Read Docs →](https://docs.oilpriceapi.com)**

---

Made with ❤️ by the OilPriceAPI Team
