feat: v1.7.0 — World-class SDK upgrade

Major improvements:

- Full async client: all 16 resources now available on AsyncOilPriceAPI (was 2)
- Add 429 auto-retry with Retry-After header support (capped at 60s)
- Add webhook signature verification (verify_signature + standalone export)
- Add oilprice CLI tool (price, historical, commodities commands with --json)
- Add opt-in telemetry (enable_telemetry=False default) on both sync and async clients
- Add async iter_pages() generator for memory-efficient pagination
- Add mkdocs + mkdocstrings API reference documentation
- Fix version triple mismatch (single source in version.py)
- Fix Python 3.8 syntax compatibility (from __future__ import annotations)
- Fix await response.json() bug in async client (httpx .json() is synchronous)
- Remove unused aiohttp dependency from [async] extra
- Export ValidationError, TimeoutError, ConfigurationError from __init__.py
- Fix get_current_price() connection leak (now uses context manager)
- Sanitize resource IDs from telemetry paths for privacy
- Extract shared validators to resource_validators.py (reduce async duplication)
- Make lint/mypy blocking in CI (removed continue-on-error)
- Add coverage enforcement gate (--cov-fail-under=50)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: karlwaldman

.github/workflows/github-pages.yml

@@ -25,13 +25,26 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install -e '.[dev]'
+          pip install mkdocs-material mkdocstrings[python]
+
+      - name: Build docs
+        run: mkdocs build
+
       - name: Setup Pages
         uses: actions/configure-pages@v4
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: './docs'
+          path: "./site"
 
       - name: Deploy to GitHub Pages
         id: deployment

.github/workflows/test.yml

@@ -30,11 +30,9 @@ jobs:
 
       - name: Lint source with ruff
         run: ruff check oilpriceapi/
-        continue-on-error: true
 
       - name: Type check with mypy
         run: mypy oilpriceapi/ --ignore-missing-imports
-        continue-on-error: true
 
       - name: Run unit tests
         run: pytest tests/ --ignore=tests/integration --ignore=tests/contract -m 'not slow' --cov=oilpriceapi --cov-report=xml -v

docs/reference/async_client.md

@@ -0,0 +1,3 @@
+# Async Client
+
+::: oilpriceapi.async_client.AsyncOilPriceAPI

docs/reference/client.md

@@ -0,0 +1,3 @@
+# Client
+
+::: oilpriceapi.client.OilPriceAPI

docs/reference/exceptions.md

@@ -0,0 +1,3 @@
+# Exceptions
+
+::: oilpriceapi.exceptions

docs/reference/models.md

@@ -0,0 +1,3 @@
+# Models
+
+::: oilpriceapi.models

docs/reference/resources.md

@@ -0,0 +1,61 @@
+# Resources
+
+## Prices
+
+::: oilpriceapi.resources.prices.PricesResource
+
+## Historical
+
+::: oilpriceapi.resources.historical.HistoricalResource
+
+## Diesel
+
+::: oilpriceapi.resources.diesel.DieselResource
+
+## Alerts
+
+::: oilpriceapi.resources.alerts.AlertsResource
+
+## Commodities
+
+::: oilpriceapi.resources.commodities.CommoditiesResource
+
+## Futures
+
+::: oilpriceapi.resources.futures.FuturesResource
+
+## Storage
+
+::: oilpriceapi.resources.storage.StorageResource
+
+## Rig Counts
+
+::: oilpriceapi.resources.rig_counts.RigCountsResource
+
+## Bunker Fuels
+
+::: oilpriceapi.resources.bunker_fuels.BunkerFuelsResource
+
+## Analytics
+
+::: oilpriceapi.resources.analytics.AnalyticsResource
+
+## Forecasts
+
+::: oilpriceapi.resources.forecasts.ForecastsResource
+
+## Data Quality
+
+::: oilpriceapi.resources.data_quality.DataQualityResource
+
+## Drilling Intelligence
+
+::: oilpriceapi.resources.drilling.DrillingIntelligenceResource
+
+## Webhooks
+
+::: oilpriceapi.resources.webhooks.WebhooksResource
+
+## Data Sources
+
+::: oilpriceapi.resources.data_sources.DataSourcesResource

mkdocs.yml

@@ -0,0 +1,39 @@
+site_name: OilPriceAPI Python SDK
+site_description: Official Python SDK for OilPriceAPI
+site_url: https://oilpriceapi.github.io/python-sdk/
+repo_url: https://github.com/oilpriceapi/python-sdk
+repo_name: oilpriceapi/python-sdk
+
+theme:
+  name: material
+  palette:
+    scheme: slate
+    primary: deep orange
+  features:
+    - content.code.copy
+    - navigation.sections
+
+nav:
+  - Home: index.md
+  - API Reference:
+      - Client: reference/client.md
+      - Async Client: reference/async_client.md
+      - Resources: reference/resources.md
+      - Models: reference/models.md
+      - Exceptions: reference/exceptions.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_source: false
+            show_root_heading: true
+            heading_level: 2
+            members_order: source
+
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - admonition

oilpriceapi/__init__.py

@@ -4,7 +4,8 @@
 The official Python SDK for OilPriceAPI - Real-time and historical oil prices.
 """
 
-__version__ = "1.5.0"
+from oilpriceapi.version import __version__
+
 __author__ = "OilPriceAPI"
 __email__ = "support@oilpriceapi.com"
 
@@ -16,6 +17,9 @@
     RateLimitError,
     DataNotFoundError,
     ServerError,
+    ValidationError,
+    TimeoutError,
+    ConfigurationError,
 )
 from oilpriceapi.models import (
     DieselPrice,
@@ -34,6 +38,9 @@
     "RateLimitError",
     "DataNotFoundError",
     "ServerError",
+    "ValidationError",
+    "TimeoutError",
+    "ConfigurationError",
     "DieselPrice",
     "DieselStation",
     "DieselStationsResponse",
@@ -42,6 +49,12 @@
     "DataConnectorPrice",
 ]
 
+from oilpriceapi.resources.webhooks import WebhooksResource
+
+# Standalone webhook signature verification
+verify_webhook_signature = WebhooksResource.verify_signature
+
+
 # Convenience function for quick access
 def get_current_price(commodity: str, api_key: str = None) -> float:
     """
@@ -59,6 +72,6 @@ def get_current_price(commodity: str, api_key: str = None) -> float:
         >>> price = opa.get_current_price("BRENT_CRUDE_USD")
         >>> print(f"Oil: ${price}")
     """
-    client = OilPriceAPI(api_key=api_key)
-    price = client.prices.get(commodity)
-    return price.value
+    with OilPriceAPI(api_key=api_key) as client:
+        price = client.prices.get(commodity)
+        return price.value