openbb-oilpriceapi 0.1.0__tar.gz

openbb_oilpriceapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

openbb_oilpriceapi-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: openbb-oilpriceapi
+Version: 0.1.0
+Summary: OpenBB provider for OilPriceAPI - Real-time oil and commodity prices (WTI, Brent, Urals, Natural Gas, Coal)
+License: MIT
+License-File: LICENSE
+Keywords: openbb,oil,commodity,api,energy,prices,wti,brent,urals
+Author: OilPriceAPI
+Author-email: support@oilpriceapi.com
+Requires-Python: >=3.10,<3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx (>=0.27.0,<0.28.0)
+Requires-Dist: openbb-core (>=1.5.1,<2.0.0)
+Requires-Dist: tenacity (>=8.2.0,<9.0.0)
+Project-URL: Repository, https://github.com/OilpriceAPI/openbb-oilpriceapi
+Description-Content-Type: text/markdown
+
+# openbb-oilpriceapi
+
+[![PyPI version](https://badge.fury.io/py/openbb-oilpriceapi.svg)](https://badge.fury.io/py/openbb-oilpriceapi)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+OpenBB provider for [OilPriceAPI](https://oilpriceapi.com) - Real-time oil and commodity prices.
+
+## Installation
+
+```bash
+pip install openbb-oilpriceapi
+```
+
+## Quick Start
+
+```python
+from openbb import obb
+
+# Configure your API key (get free key at https://oilpriceapi.com/signup)
+obb.user.credentials.oilpriceapi_api_key = "your_api_key"
+
+# Get all commodity prices
+prices = obb.commodity.oil.price(provider="oilpriceapi")
+df = prices.to_dataframe()
+print(df)
+
+# Get specific commodity (WTI crude)
+wti = obb.commodity.oil.price(symbol="WTI", provider="oilpriceapi")
+print(f"WTI Price: ${wti.results[0].price}/barrel")
+```
+
+## Supported Commodities
+
+| Symbol | Name | Description |
+|--------|------|-------------|
+| `WTI` | WTI Crude Oil | West Texas Intermediate benchmark |
+| `BRENT` | Brent Crude Oil | North Sea benchmark |
+| `URALS` | Urals Crude Oil | Russian export blend |
+| `DUBAI` | Dubai Crude Oil | Middle East benchmark |
+| `NG` | Natural Gas (US) | Henry Hub |
+| `NG_EU` | Natural Gas (EU) | TTF |
+| `NG_UK` | Natural Gas (UK) | NBP |
+| `COAL` | Coal | Thermal coal |
+| `DIESEL_US` | US Diesel | National average |
+| `GASOLINE_US` | US Gasoline | National average |
+
+## Configuration
+
+### Set Credentials
+
+You can set your API key in multiple ways:
+
+**Option 1: In Python**
+```python
+obb.user.credentials.oilpriceapi_api_key = "your_key"
+```
+
+**Option 2: Via settings file**
+Add to `~/.openbb_platform/user_settings.json`:
+```json
+{
+  "credentials": {
+    "oilpriceapi_api_key": "your_key"
+  }
+}
+```
+
+**Option 3: Environment variable**
+```bash
+export OPENBB_OILPRICEAPI_API_KEY="your_key"
+```
+
+## Examples
+
+### Get Price History
+
+```python
+# Get WTI prices for the past week
+history = obb.commodity.oil.historical(
+    symbol="WTI",
+    period="past_week",
+    provider="oilpriceapi"
+)
+df = history.to_dataframe()
+```
+
+### Compare Commodities
+
+```python
+import pandas as pd
+
+# Get all prices and compare
+prices = obb.commodity.oil.price(provider="oilpriceapi")
+df = prices.to_dataframe()
+
+# Filter for crude oils
+crude = df[df['symbol'].isin(['WTI', 'BRENT', 'URALS'])]
+print(crude[['symbol', 'price', 'change_percent']])
+```
+
+### Visualize Prices
+
+```python
+import matplotlib.pyplot as plt
+
+history = obb.commodity.oil.historical(
+    symbol="BRENT",
+    period="past_month",
+    provider="oilpriceapi"
+)
+df = history.to_dataframe()
+
+plt.figure(figsize=(10, 6))
+plt.plot(df['date'], df['price'])
+plt.title('Brent Crude - Past Month')
+plt.ylabel('Price (USD/barrel)')
+plt.show()
+```
+
+## API Reference
+
+### OilPrice
+
+Fetch latest commodity prices.
+
+**Parameters:**
+- `symbol` (str, optional): Commodity symbol. If not provided, returns all commodities.
+- `provider` (str): Must be "oilpriceapi"
+
+**Returns:**
+- `symbol`: Commodity symbol
+- `name`: Commodity name
+- `price`: Current price
+- `currency`: Price currency
+- `unit`: Unit of measurement
+- `updated_at`: Last update timestamp
+- `change`: Price change (absolute)
+- `change_percent`: Price change (percentage)
+
+### OilHistorical
+
+Fetch historical price data.
+
+**Parameters:**
+- `symbol` (str, required): Commodity symbol
+- `period` (str): Historical period - `past_day` (24h hourly), `past_week` (7d daily), `past_month` (30d daily). Default: `past_week`
+- `provider` (str): Must be "oilpriceapi"
+
+**Returns:**
+- `date`: Price timestamp
+- `symbol`: Commodity symbol
+- `price`: Price at timestamp
+- `currency`: Price currency
+- `unit`: Unit of measurement
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/OilpriceAPI/openbb-oilpriceapi.git
+cd openbb-oilpriceapi
+
+# Install dependencies
+poetry install
+
+# Run tests
+poetry run pytest
+
+# Run tests with coverage
+poetry run pytest --cov=openbb_oilpriceapi
+```
+
+## Links
+
+- [OilPriceAPI Website](https://oilpriceapi.com)
+- [OilPriceAPI Documentation](https://docs.oilpriceapi.com)
+- [OpenBB Platform](https://openbb.co)
+- [GitHub Repository](https://github.com/OilpriceAPI/openbb-oilpriceapi)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

openbb_oilpriceapi-0.1.0/README.md

@@ -0,0 +1,182 @@
+# openbb-oilpriceapi
+
+[![PyPI version](https://badge.fury.io/py/openbb-oilpriceapi.svg)](https://badge.fury.io/py/openbb-oilpriceapi)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+OpenBB provider for [OilPriceAPI](https://oilpriceapi.com) - Real-time oil and commodity prices.
+
+## Installation
+
+```bash
+pip install openbb-oilpriceapi
+```
+
+## Quick Start
+
+```python
+from openbb import obb
+
+# Configure your API key (get free key at https://oilpriceapi.com/signup)
+obb.user.credentials.oilpriceapi_api_key = "your_api_key"
+
+# Get all commodity prices
+prices = obb.commodity.oil.price(provider="oilpriceapi")
+df = prices.to_dataframe()
+print(df)
+
+# Get specific commodity (WTI crude)
+wti = obb.commodity.oil.price(symbol="WTI", provider="oilpriceapi")
+print(f"WTI Price: ${wti.results[0].price}/barrel")
+```
+
+## Supported Commodities
+
+| Symbol | Name | Description |
+|--------|------|-------------|
+| `WTI` | WTI Crude Oil | West Texas Intermediate benchmark |
+| `BRENT` | Brent Crude Oil | North Sea benchmark |
+| `URALS` | Urals Crude Oil | Russian export blend |
+| `DUBAI` | Dubai Crude Oil | Middle East benchmark |
+| `NG` | Natural Gas (US) | Henry Hub |
+| `NG_EU` | Natural Gas (EU) | TTF |
+| `NG_UK` | Natural Gas (UK) | NBP |
+| `COAL` | Coal | Thermal coal |
+| `DIESEL_US` | US Diesel | National average |
+| `GASOLINE_US` | US Gasoline | National average |
+
+## Configuration
+
+### Set Credentials
+
+You can set your API key in multiple ways:
+
+**Option 1: In Python**
+```python
+obb.user.credentials.oilpriceapi_api_key = "your_key"
+```
+
+**Option 2: Via settings file**
+Add to `~/.openbb_platform/user_settings.json`:
+```json
+{
+  "credentials": {
+    "oilpriceapi_api_key": "your_key"
+  }
+}
+```
+
+**Option 3: Environment variable**
+```bash
+export OPENBB_OILPRICEAPI_API_KEY="your_key"
+```
+
+## Examples
+
+### Get Price History
+
+```python
+# Get WTI prices for the past week
+history = obb.commodity.oil.historical(
+    symbol="WTI",
+    period="past_week",
+    provider="oilpriceapi"
+)
+df = history.to_dataframe()
+```
+
+### Compare Commodities
+
+```python
+import pandas as pd
+
+# Get all prices and compare
+prices = obb.commodity.oil.price(provider="oilpriceapi")
+df = prices.to_dataframe()
+
+# Filter for crude oils
+crude = df[df['symbol'].isin(['WTI', 'BRENT', 'URALS'])]
+print(crude[['symbol', 'price', 'change_percent']])
+```
+
+### Visualize Prices
+
+```python
+import matplotlib.pyplot as plt
+
+history = obb.commodity.oil.historical(
+    symbol="BRENT",
+    period="past_month",
+    provider="oilpriceapi"
+)
+df = history.to_dataframe()
+
+plt.figure(figsize=(10, 6))
+plt.plot(df['date'], df['price'])
+plt.title('Brent Crude - Past Month')
+plt.ylabel('Price (USD/barrel)')
+plt.show()
+```
+
+## API Reference
+
+### OilPrice
+
+Fetch latest commodity prices.
+
+**Parameters:**
+- `symbol` (str, optional): Commodity symbol. If not provided, returns all commodities.
+- `provider` (str): Must be "oilpriceapi"
+
+**Returns:**
+- `symbol`: Commodity symbol
+- `name`: Commodity name
+- `price`: Current price
+- `currency`: Price currency
+- `unit`: Unit of measurement
+- `updated_at`: Last update timestamp
+- `change`: Price change (absolute)
+- `change_percent`: Price change (percentage)
+
+### OilHistorical
+
+Fetch historical price data.
+
+**Parameters:**
+- `symbol` (str, required): Commodity symbol
+- `period` (str): Historical period - `past_day` (24h hourly), `past_week` (7d daily), `past_month` (30d daily). Default: `past_week`
+- `provider` (str): Must be "oilpriceapi"
+
+**Returns:**
+- `date`: Price timestamp
+- `symbol`: Commodity symbol
+- `price`: Price at timestamp
+- `currency`: Price currency
+- `unit`: Unit of measurement
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/OilpriceAPI/openbb-oilpriceapi.git
+cd openbb-oilpriceapi
+
+# Install dependencies
+poetry install
+
+# Run tests
+poetry run pytest
+
+# Run tests with coverage
+poetry run pytest --cov=openbb_oilpriceapi
+```
+
+## Links
+
+- [OilPriceAPI Website](https://oilpriceapi.com)
+- [OilPriceAPI Documentation](https://docs.oilpriceapi.com)
+- [OpenBB Platform](https://openbb.co)
+- [GitHub Repository](https://github.com/OilpriceAPI/openbb-oilpriceapi)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

openbb_oilpriceapi-0.1.0/openbb_oilpriceapi/__init__.py

@@ -0,0 +1,55 @@
+"""OpenBB OilPriceAPI Provider Module.
+
+This provider enables access to real-time oil and commodity prices
+from OilPriceAPI through the OpenBB Platform.
+
+Supported commodities:
+- WTI Crude Oil (WTI)
+- Brent Crude Oil (BRENT)
+- Urals Crude Oil (URALS)
+- Dubai Crude Oil (DUBAI)
+- Natural Gas US (NG)
+- Natural Gas EU (NG_EU)
+- Natural Gas UK (NG_UK)
+- Coal (COAL)
+- Diesel US (DIESEL_US)
+- Gasoline US (GASOLINE_US)
+
+Usage:
+    from openbb import obb
+
+    # Configure credentials
+    obb.user.credentials.oilpriceapi_api_key = "your_api_key"
+
+    # Get all prices
+    prices = obb.commodity.oil.price(provider="oilpriceapi")
+
+    # Get specific commodity
+    wti = obb.commodity.oil.price(symbol="WTI", provider="oilpriceapi")
+"""
+
+from openbb_core.provider.abstract.provider import Provider
+from openbb_oilpriceapi.models.oil_price import OilPriceAPIFetcher
+from openbb_oilpriceapi.models.oil_historical import OilHistoricalFetcher
+
+oilpriceapi_provider = Provider(
+    name="oilpriceapi",
+    website="https://oilpriceapi.com",
+    description=(
+        "OilPriceAPI provides real-time and historical oil and commodity prices "
+        "including WTI, Brent, Urals crude oil, natural gas, coal, and diesel. "
+        "Get your free API key at https://oilpriceapi.com"
+    ),
+    credentials=["api_key"],
+    fetcher_dict={
+        "OilPrice": OilPriceAPIFetcher,
+        "OilHistorical": OilHistoricalFetcher,
+    },
+    repr_name="OilPriceAPI",
+    instructions=(
+        "Get your free API key at https://oilpriceapi.com/signup\n"
+        "Set credentials: obb.user.credentials.oilpriceapi_api_key = 'your_key'"
+    ),
+)
+
+__all__ = ["oilpriceapi_provider"]

openbb_oilpriceapi-0.1.0/openbb_oilpriceapi/models/__init__.py

@@ -0,0 +1,29 @@
+"""OilPriceAPI models."""
+
+from openbb_oilpriceapi.models.oil_price import (
+    OilPriceAPIFetcher,
+    OilPriceAPIQueryParams,
+    OilPriceAPIData,
+    OilPriceAPIError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+)
+from openbb_oilpriceapi.models.oil_historical import (
+    OilHistoricalFetcher,
+    OilHistoricalQueryParams,
+    OilHistoricalData,
+)
+
+__all__ = [
+    "OilPriceAPIFetcher",
+    "OilPriceAPIQueryParams",
+    "OilPriceAPIData",
+    "OilPriceAPIError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "OilHistoricalFetcher",
+    "OilHistoricalQueryParams",
+    "OilHistoricalData",
+]

openbb_oilpriceapi-0.1.0/openbb_oilpriceapi/models/oil_historical.py

@@ -0,0 +1,208 @@
+"""OilPriceAPI Historical Price model and fetcher."""
+
+from datetime import datetime
+from typing import Any, Literal
+
+import httpx
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.abstract.query_params import QueryParams
+from openbb_core.provider.abstract.data import Data
+from pydantic import Field, field_validator
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
+
+from openbb_oilpriceapi.utils.constants import (
+    SYMBOL_MAPPING,
+    AVAILABLE_SYMBOLS,
+    OILPRICEAPI_BASE_URL,
+    REVERSE_SYMBOL_MAPPING,
+)
+from openbb_oilpriceapi.models.oil_price import (
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+)
+
+
+# Supported historical periods
+HISTORICAL_PERIODS = ["past_day", "past_week", "past_month"]
+
+
+class OilHistoricalQueryParams(QueryParams):
+    """OilPriceAPI Historical Query Parameters.
+
+    Source: https://oilpriceapi.com
+    """
+
+    __json_schema_extra__ = {
+        "symbol": {
+            "multiple_items_allowed": False,
+            "choices": AVAILABLE_SYMBOLS,
+        },
+        "period": {
+            "multiple_items_allowed": False,
+            "choices": HISTORICAL_PERIODS,
+        },
+    }
+
+    symbol: str = Field(
+        description="The commodity symbol to fetch historical data for. "
+        f"Available symbols: {', '.join(AVAILABLE_SYMBOLS)}",
+    )
+    period: Literal["past_day", "past_week", "past_month"] = Field(
+        default="past_week",
+        description="Historical period: past_day (24h hourly), past_week (7d daily), past_month (30d daily).",
+    )
+
+    @field_validator("symbol", mode="before")
+    @classmethod
+    def validate_symbol(cls, v: str) -> str:
+        """Validate that symbol is in the list of available symbols."""
+        v_upper = v.upper()
+        if v_upper not in AVAILABLE_SYMBOLS:
+            raise ValueError(
+                f"Invalid symbol '{v}'. Available symbols: {', '.join(AVAILABLE_SYMBOLS)}"
+            )
+        return v_upper
+
+
+class OilHistoricalData(Data):
+    """OilPriceAPI Historical Price Data Model."""
+
+    date: datetime = Field(description="The timestamp of the price data point.")
+    symbol: str = Field(description="The commodity symbol/code.")
+    price: float = Field(description="The price at this timestamp.")
+    currency: str = Field(default="USD", description="The price currency.")
+    unit: str = Field(default="barrel", description="The unit of measurement.")
+
+
+class OilHistoricalFetcher(Fetcher[OilHistoricalQueryParams, list[OilHistoricalData]]):
+    """OilPriceAPI Historical Price Fetcher."""
+
+    require_credentials = True
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> OilHistoricalQueryParams:
+        """Transform the query parameters."""
+        return OilHistoricalQueryParams(**params)
+
+    @staticmethod
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=10),
+        retry=retry_if_exception_type(RateLimitError),
+        reraise=True,
+    )
+    async def _fetch_with_retry(
+        client: httpx.AsyncClient,
+        url: str,
+        headers: dict[str, str],
+    ) -> dict[str, Any]:
+        """Fetch data with retry logic for rate limits."""
+        response = await client.get(url, headers=headers)
+
+        if response.status_code == 401:
+            raise AuthenticationError(
+                "Invalid API key. Check your OilPriceAPI credentials."
+            )
+        if response.status_code == 429:
+            raise RateLimitError(
+                "Rate limit exceeded. Retrying with exponential backoff..."
+            )
+        if response.status_code == 404:
+            raise NotFoundError("Commodity not found.")
+
+        response.raise_for_status()
+        return response.json()
+
+    @staticmethod
+    async def aextract_data(
+        query: OilHistoricalQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """Extract historical data from OilPriceAPI."""
+        api_key = credentials.get("api_key") if credentials else None
+        if not api_key:
+            raise AuthenticationError(
+                "OilPriceAPI API key is required. "
+                "Get a free key at https://oilpriceapi.com"
+            )
+
+        headers = {
+            "Authorization": f"Token {api_key}",
+            "Accept": "application/json",
+        }
+
+        # Map OpenBB symbol to OilPriceAPI code
+        oilpriceapi_code = SYMBOL_MAPPING.get(query.symbol, query.symbol)
+        url = f"{OILPRICEAPI_BASE_URL}/prices/{query.period}?by_code={oilpriceapi_code}"
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            try:
+                data = await OilHistoricalFetcher._fetch_with_retry(
+                    client, url, headers
+                )
+            except RateLimitError:
+                raise RateLimitError(
+                    "Rate limit exceeded after 3 retries. "
+                    "Please wait before making more requests."
+                )
+
+            # Handle response structure
+            if "data" in data:
+                if "prices" in data["data"]:
+                    return data["data"]["prices"]
+                elif isinstance(data["data"], list):
+                    return data["data"]
+
+            return []
+
+    @staticmethod
+    def transform_data(
+        query: OilHistoricalQueryParams,
+        data: list[dict[str, Any]],
+        **kwargs: Any,
+    ) -> list[OilHistoricalData]:
+        """Transform API response to OilHistoricalData models."""
+        results = []
+
+        for item in data:
+            # Parse the timestamp
+            date_str = item.get("created_at") or item.get("date") or item.get("timestamp")
+            if date_str:
+                if isinstance(date_str, str):
+                    date_str = date_str.replace("Z", "+00:00")
+                    try:
+                        date = datetime.fromisoformat(date_str)
+                    except ValueError:
+                        continue  # Skip invalid dates
+                else:
+                    date = date_str
+            else:
+                continue  # Skip entries without dates
+
+            # Get symbol from query (historical data is for specific symbol)
+            symbol = query.symbol
+
+            # Clean up unit string
+            unit = item.get("unit", "").replace("per ", "").strip() or "barrel"
+
+            results.append(
+                OilHistoricalData(
+                    date=date,
+                    symbol=symbol,
+                    price=float(item.get("price", 0)),
+                    currency=item.get("currency", "USD"),
+                    unit=unit,
+                )
+            )
+
+        # Sort by date ascending
+        results.sort(key=lambda x: x.date)
+
+        return results

openbb_oilpriceapi-0.1.0/openbb_oilpriceapi/models/oil_price.py

@@ -0,0 +1,234 @@
+"""OilPriceAPI Oil Price model and fetcher."""
+
+from datetime import datetime
+from typing import Any
+
+import httpx
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.abstract.query_params import QueryParams
+from openbb_core.provider.abstract.data import Data
+from pydantic import Field, field_validator
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
+
+from openbb_oilpriceapi.utils.constants import (
+    SYMBOL_MAPPING,
+    AVAILABLE_SYMBOLS,
+    OILPRICEAPI_BASE_URL,
+    REVERSE_SYMBOL_MAPPING,
+)
+
+
+class OilPriceAPIError(Exception):
+    """Base exception for OilPriceAPI errors."""
+
+    pass
+
+
+class AuthenticationError(OilPriceAPIError):
+    """Raised when API key is invalid or missing."""
+
+    pass
+
+
+class RateLimitError(OilPriceAPIError):
+    """Raised when rate limit is exceeded."""
+
+    pass
+
+
+class NotFoundError(OilPriceAPIError):
+    """Raised when commodity is not found."""
+
+    pass
+
+
+class OilPriceAPIQueryParams(QueryParams):
+    """OilPriceAPI Query Parameters.
+
+    Source: https://oilpriceapi.com
+    """
+
+    __json_schema_extra__ = {
+        "symbol": {
+            "multiple_items_allowed": False,
+            "choices": AVAILABLE_SYMBOLS,
+        }
+    }
+
+    symbol: str | None = Field(
+        default=None,
+        description="The commodity symbol to fetch. If None, returns all available commodities. "
+        f"Available symbols: {', '.join(AVAILABLE_SYMBOLS)}",
+    )
+
+    @field_validator("symbol", mode="before")
+    @classmethod
+    def validate_symbol(cls, v: str | None) -> str | None:
+        """Validate that symbol is in the list of available symbols."""
+        if v is None:
+            return v
+        v_upper = v.upper()
+        if v_upper not in AVAILABLE_SYMBOLS:
+            raise ValueError(
+                f"Invalid symbol '{v}'. Available symbols: {', '.join(AVAILABLE_SYMBOLS)}"
+            )
+        return v_upper
+
+
+class OilPriceAPIData(Data):
+    """OilPriceAPI Oil Price Data Model."""
+
+    symbol: str = Field(description="The commodity symbol/code.")
+    name: str = Field(description="The commodity name.")
+    price: float = Field(description="The current price.")
+    currency: str = Field(description="The price currency (e.g., USD).")
+    unit: str = Field(description="The unit of measurement (e.g., barrel, therm).")
+    updated_at: datetime = Field(description="The timestamp of the last price update.")
+    change: float | None = Field(
+        default=None, description="The absolute price change."
+    )
+    change_percent: float | None = Field(
+        default=None, description="The percentage price change."
+    )
+
+
+class OilPriceAPIFetcher(Fetcher[OilPriceAPIQueryParams, list[OilPriceAPIData]]):
+    """OilPriceAPI Oil Price Fetcher."""
+
+    require_credentials = True
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> OilPriceAPIQueryParams:
+        """Transform the query parameters."""
+        return OilPriceAPIQueryParams(**params)
+
+    @staticmethod
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=10),
+        retry=retry_if_exception_type(RateLimitError),
+        reraise=True,
+    )
+    async def _fetch_with_retry(
+        client: httpx.AsyncClient,
+        url: str,
+        headers: dict[str, str],
+    ) -> dict[str, Any]:
+        """Fetch data with retry logic for rate limits."""
+        response = await client.get(url, headers=headers)
+
+        if response.status_code == 401:
+            raise AuthenticationError(
+                "Invalid API key. Check your OilPriceAPI credentials."
+            )
+        if response.status_code == 429:
+            raise RateLimitError(
+                "Rate limit exceeded. Retrying with exponential backoff..."
+            )
+        if response.status_code == 404:
+            raise NotFoundError("Commodity not found.")
+
+        response.raise_for_status()
+        return response.json()
+
+    @staticmethod
+    async def aextract_data(
+        query: OilPriceAPIQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """Extract data from OilPriceAPI."""
+        api_key = credentials.get("api_key") if credentials else None
+        if not api_key:
+            raise AuthenticationError(
+                "OilPriceAPI API key is required. "
+                "Get a free key at https://oilpriceapi.com"
+            )
+
+        headers = {
+            "Authorization": f"Token {api_key}",
+            "Accept": "application/json",
+        }
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            # Determine endpoint based on symbol
+            if query.symbol:
+                # Map OpenBB symbol to OilPriceAPI code
+                oilpriceapi_code = SYMBOL_MAPPING.get(query.symbol, query.symbol)
+                url = f"{OILPRICEAPI_BASE_URL}/prices/latest?by_code={oilpriceapi_code}"
+            else:
+                url = f"{OILPRICEAPI_BASE_URL}/prices/latest"
+
+            try:
+                data = await OilPriceAPIFetcher._fetch_with_retry(client, url, headers)
+            except RateLimitError:
+                # Re-raise with user-friendly message after retries exhausted
+                raise RateLimitError(
+                    "Rate limit exceeded after 3 retries. "
+                    "Please wait before making more requests."
+                )
+
+            # Handle different response structures
+            if "data" in data:
+                if "prices" in data["data"]:
+                    # Multiple prices response
+                    return data["data"]["prices"]
+                elif "price" in data["data"]:
+                    # Single price response
+                    return [data["data"]["price"]]
+                else:
+                    return [data["data"]]
+
+            return []
+
+    @staticmethod
+    def transform_data(
+        query: OilPriceAPIQueryParams,
+        data: list[dict[str, Any]],
+        **kwargs: Any,
+    ) -> list[OilPriceAPIData]:
+        """Transform API response to OilPriceAPIData models."""
+        results = []
+
+        for item in data:
+            # Parse the timestamp
+            updated_at_str = item.get("created_at") or item.get("updated_at")
+            if updated_at_str:
+                if isinstance(updated_at_str, str):
+                    # Handle ISO format with or without Z suffix
+                    updated_at_str = updated_at_str.replace("Z", "+00:00")
+                    try:
+                        updated_at = datetime.fromisoformat(updated_at_str)
+                    except ValueError:
+                        updated_at = datetime.now()
+                else:
+                    updated_at = updated_at_str
+            else:
+                updated_at = datetime.now()
+
+            # Get the symbol - use OpenBB symbol if available
+            raw_symbol = item.get("code", item.get("symbol", "UNKNOWN"))
+            symbol = REVERSE_SYMBOL_MAPPING.get(raw_symbol, raw_symbol)
+
+            # Clean up unit string
+            unit = item.get("unit", "").replace("per ", "").strip()
+
+            results.append(
+                OilPriceAPIData(
+                    symbol=symbol,
+                    name=item.get("name", ""),
+                    price=float(item.get("price", 0)),
+                    currency=item.get("currency", "USD"),
+                    unit=unit or "barrel",
+                    updated_at=updated_at,
+                    change=item.get("change"),
+                    change_percent=item.get("change_percent"),
+                )
+            )
+
+        return results

openbb_oilpriceapi-0.1.0/openbb_oilpriceapi/utils/__init__.py

@@ -0,0 +1,9 @@
+"""OilPriceAPI utilities."""
+
+from openbb_oilpriceapi.utils.constants import (
+    SYMBOL_MAPPING,
+    AVAILABLE_SYMBOLS,
+    OILPRICEAPI_BASE_URL,
+)
+
+__all__ = ["SYMBOL_MAPPING", "AVAILABLE_SYMBOLS", "OILPRICEAPI_BASE_URL"]

openbb_oilpriceapi-0.1.0/openbb_oilpriceapi/utils/constants.py

@@ -0,0 +1,44 @@
+"""OilPriceAPI constants and symbol mappings."""
+
+from typing import Literal
+
+# Base URL for OilPriceAPI
+OILPRICEAPI_BASE_URL = "https://api.oilpriceapi.com/v1"
+
+# Mapping from OpenBB symbols to OilPriceAPI commodity codes
+SYMBOL_MAPPING: dict[str, str] = {
+    # Crude Oil
+    "WTI": "WTI_USD",
+    "BRENT": "BRENT_CRUDE_USD",
+    "URALS": "URALS_USD",
+    "DUBAI": "DUBAI_CRUDE_USD",
+    # Natural Gas
+    "NG": "NATURAL_GAS_USD",
+    "NG_EU": "NATURAL_GAS_EU",
+    "NG_UK": "NATURAL_GAS_GBP",
+    # Coal
+    "COAL": "COAL_USD",
+    # Diesel/Gasoline
+    "DIESEL_US": "DIESEL_US_NATIONAL",
+    "GASOLINE_US": "GASOLINE_US_NATIONAL",
+}
+
+# Reverse mapping for transforming API responses
+REVERSE_SYMBOL_MAPPING: dict[str, str] = {v: k for k, v in SYMBOL_MAPPING.items()}
+
+# List of available symbols for validation
+AVAILABLE_SYMBOLS: list[str] = list(SYMBOL_MAPPING.keys())
+
+# Type for symbol literals (for type hints)
+SymbolType = Literal[
+    "WTI",
+    "BRENT",
+    "URALS",
+    "DUBAI",
+    "NG",
+    "NG_EU",
+    "NG_UK",
+    "COAL",
+    "DIESEL_US",
+    "GASOLINE_US",
+]

openbb_oilpriceapi-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[tool.poetry]
+name = "openbb-oilpriceapi"
+version = "0.1.0"
+description = "OpenBB provider for OilPriceAPI - Real-time oil and commodity prices (WTI, Brent, Urals, Natural Gas, Coal)"
+authors = ["OilPriceAPI <support@oilpriceapi.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "openbb_oilpriceapi" }]
+repository = "https://github.com/OilpriceAPI/openbb-oilpriceapi"
+keywords = ["openbb", "oil", "commodity", "api", "energy", "prices", "wti", "brent", "urals"]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.14"
+openbb-core = "^1.5.1"
+httpx = "^0.27.0"
+tenacity = "^8.2.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+pytest-cov = "^4.1.0"
+respx = "^0.21.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.plugins."openbb_provider_extension"]
+oilpriceapi = "openbb_oilpriceapi:oilpriceapi_provider"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["openbb_oilpriceapi"]