From 04f8e3a6f56630015b35a25b356c2aaed70b3f08 Mon Sep 17 00:00:00 2001 From: Karl Waldman Date: Fri, 3 Jul 2026 09:57:57 -0400 Subject: [PATCH 1/2] docs: registry storefront README + v1.10.1 Apply the shared registry-storefront formula from the PHP SDK: - hero line (oil/gas/LNG/carbon/fuels in under 60 seconds) + audience line + 2M+ requests/month - shields.io pypi/v badge, nav line with utm_source=python-sdk and quick-start jump link - "What can you get?" 10-commodity table after the hero - "The whole OilPriceAPI toolbox" cross-SDK table before Testing - bump version to 1.10.1 (version.py + pyproject.toml) so PyPI re-renders the README Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 6 +++++ README.md | 51 +++++++++++++++++++++++++++--------------- oilpriceapi/version.py | 2 +- pyproject.toml | 2 +- 4 files changed, 41 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ece71d6..9b67ab6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.10.1] - 2026-07-03 + +### Changed + +- docs: registry storefront README — hero, "What can you get?" commodity table, and cross-SDK toolbox table so the PyPI page matches the other OilPriceAPI SDKs. No code changes. + ## [1.10.0] - 2026-07-03 ### Added diff --git a/README.md b/README.md index 4b60598..e03ed3a 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,36 @@ # OilPriceAPI Python SDK -> **Real-time oil and commodity price data for Python** - Professional-grade API at 98% less cost than Bloomberg Terminal +> **Real-time oil, gas, LNG, carbon and fuel prices in your Python app in under 60 seconds** — typed client, pandas DataFrames, async + WebSocket streaming, and technical indicators built in. -[![PyPI version](https://badge.fury.io/py/oilpriceapi.svg)](https://badge.fury.io/py/oilpriceapi) +[![PyPI version](https://img.shields.io/pypi/v/oilpriceapi)](https://pypi.org/project/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://www.oilpriceapi.com/signup?utm_source=pypi&utm_medium=sdk&utm_campaign=readme)** • **[Documentation](https://docs.oilpriceapi.com/)** • **[Pricing](https://www.oilpriceapi.com/pricing?utm_source=pypi&utm_medium=sdk&utm_campaign=pricing)** +**[Get a Free API Key](https://www.oilpriceapi.com/auth/signup?utm_source=python-sdk)** · **[Documentation](https://docs.oilpriceapi.com)** · **[Pricing](https://www.oilpriceapi.com/pricing?utm_source=python-sdk-limit)** · **[Quick start ↓](#-quick-start)** -The official Python SDK for [OilPriceAPI](https://oilpriceapi.com) - Real-time and historical oil prices for Brent Crude, WTI, Natural Gas, and more. +The official Python SDK for [OilPriceAPI](https://oilpriceapi.com), the commodity price API behind fintech dashboards, fleet & logistics tools, maritime compliance platforms and energy analytics products — serving **2M+ API requests every month**. > **📝 Documentation Status**: All code examples shown are tested and working. Technical indicators are available as of v1.10.0 (see [Technical Indicators](#technical-indicators-new-in-v1100)); see our [GitHub Issues](https://github.com/OilpriceAPI/python-sdk/issues) for the roadmap. -**Quick start:** +## What can you get? -```bash -pip install oilpriceapi -``` +110+ commodities across the energy complex. The ones our customers poll the most: + +| Code | What it is | Typical use | +| ----------------- | -------------------------- | ------------------------------------------- | +| `BRENT_CRUDE_USD` | Brent crude (global) | dashboards, market context, deal models | +| `WTI_USD` | WTI crude (US) | trading tools, macro models | +| `NATURAL_GAS_USD` | Henry Hub natural gas | energy analytics, procurement | +| `DUTCH_TTF_EUR` | TTF gas (Europe) | European energy, LNG analytics | +| `JKM_LNG_USD` | JKM LNG (Asia) | LNG trading & shipping | +| `EU_CARBON_EUR` | EU ETS carbon allowances | CBAM reporting, maritime compliance, ESG | +| `DIESEL_USD` | Diesel (Gulf Coast) | fleet fuel-surcharge calculators, logistics | +| `JET_FUEL_USD` | Jet fuel | aviation ops & charter pricing | +| `VLSFO_USD` | Marine bunker fuel (0.5%S) | voyage costing, bunker procurement | +| `GOLD_USD` | Gold | macro & portfolio context | ## 🚀 Quick Start @@ -723,6 +734,20 @@ stream = client.stream.prices( > WebSocket streaming requires a Professional+ plan. Subscriptions from > lower tiers are rejected during the ActionCable handshake. +## The whole OilPriceAPI toolbox + +Same data, every stack: + +| Tool | Install | +| ----------------------------------------------------------------------------------- | ---------------------------------------------- | +| [Node/TypeScript SDK](https://github.com/OilpriceAPI/oilpriceapi-node) | `npm install oilpriceapi` | +| [Go SDK](https://github.com/OilpriceAPI/oilpriceapi-go) | `go get github.com/OilpriceAPI/oilpriceapi-go` | +| [PHP SDK](https://github.com/OilpriceAPI/oilpriceapi-php) | `composer require oilpriceapi/oilpriceapi` | +| [MCP server](https://github.com/OilpriceAPI/mcp-server) (Claude, Cursor, AI agents) | `npx -y oilpriceapi-mcp` | +| [WordPress plugin](https://github.com/OilpriceAPI/oilpriceapi-wordpress-plugin) | wordpress.org, no code | +| [Google Sheets Add-on](https://github.com/OilpriceAPI/google-sheets-addin) | custom spreadsheet functions | +| [Excel Add-in](https://github.com/OilpriceAPI/excel-energy-addin) | energy prices in Excel | + ## 🧪 Testing The SDK uses standard Python testing frameworks. Example using pytest: @@ -851,14 +876,4 @@ Contributions are welcome! Please see our [Contributing Guide](https://github.co --- -## Also Available As - -- **[Node.js SDK](https://www.npmjs.com/package/oilpriceapi)** - TypeScript/JavaScript SDK for Node.js -- **[Go SDK](https://github.com/OilpriceAPI/oilpriceapi-go)** - Idiomatic Go client -- **[MCP Server](https://www.npmjs.com/package/oilpriceapi-mcp)** - Model Context Protocol server for Claude, Cursor, and VS Code -- **[Google Sheets Add-on](https://github.com/OilpriceAPI/google-sheets-addin)** - Custom functions for spreadsheets -- **[Excel Add-in](https://github.com/OilpriceAPI/excel-energy-addin)** - Energy price comparison in Excel - ---- - Made with care by the OilPriceAPI Team diff --git a/oilpriceapi/version.py b/oilpriceapi/version.py index 2aa36e3..541b68b 100644 --- a/oilpriceapi/version.py +++ b/oilpriceapi/version.py @@ -5,6 +5,6 @@ Used in __init__.py, client.py, and async_client.py. """ -__version__ = "1.10.0" +__version__ = "1.10.1" SDK_VERSION = __version__ SDK_NAME = "oilpriceapi-python" diff --git a/pyproject.toml b/pyproject.toml index f772332..110692e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "oilpriceapi" -version = "1.10.0" +version = "1.10.1" description = "Official Python SDK for OilPriceAPI - Real-time and historical oil prices" authors = [ {name = "OilPriceAPI", email = "support@oilpriceapi.com"} From f02b714f24497dbb15f6cbfb402a9cf82d776f62 Mon Sep 17 00:00:00 2001 From: Karl Waldman Date: Fri, 3 Jul 2026 10:04:57 -0400 Subject: [PATCH 2/2] fix: accept numeric market-brief confidence + link API explorer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Live contract tests (first run with a real key) caught the API sending confidence: 0.65 (float) where the model required a string label — now Union[str, float]. Also links the interactive Swagger explorer and raw OpenAPI spec from the README (they existed, unadvertised). Co-Authored-By: Claude Fable 5 --- README.md | 4 +++- oilpriceapi/models.py | 9 +++++++-- tests/unit/test_subscriptions_resource.py | 17 +++++++++++++++++ 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e03ed3a..24cbabe 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ [![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 a Free API Key](https://www.oilpriceapi.com/auth/signup?utm_source=python-sdk)** · **[Documentation](https://docs.oilpriceapi.com)** · **[Pricing](https://www.oilpriceapi.com/pricing?utm_source=python-sdk-limit)** · **[Quick start ↓](#-quick-start)** +**[Get a Free API Key](https://www.oilpriceapi.com/auth/signup?utm_source=python-sdk)** · **[Documentation](https://docs.oilpriceapi.com)** · **[Pricing](https://www.oilpriceapi.com/pricing?utm_source=python-sdk-limit)** · **[API Explorer](https://api.oilpriceapi.com/swagger)** · **[Quick start ↓](#-quick-start)** The official Python SDK for [OilPriceAPI](https://oilpriceapi.com), the commodity price API behind fintech dashboards, fleet & logistics tools, maritime compliance platforms and energy analytics products — serving **2M+ API requests every month**. @@ -849,6 +849,8 @@ Contributions are welcome! Please see our [Contributing Guide](https://github.co - 📧 Email: support@oilpriceapi.com - 🐛 Issues: [GitHub Issues](https://github.com/oilpriceapi/python-sdk/issues) +- 🧭 Interactive API Explorer: [api.oilpriceapi.com/swagger](https://api.oilpriceapi.com/swagger) — try every endpoint in the browser (works in demo mode, no key needed) +- 📜 OpenAPI spec: [swagger.json](https://api.oilpriceapi.com/swagger.json) — generate clients, mock servers, or import into Postman/Insomnia - 📖 Docs: [Documentation](https://docs.oilpriceapi.com/) ## 🔗 Links diff --git a/oilpriceapi/models.py b/oilpriceapi/models.py index c3f41f4..803e101 100644 --- a/oilpriceapi/models.py +++ b/oilpriceapi/models.py @@ -5,7 +5,7 @@ """ from datetime import datetime -from typing import Any, Dict, List, Optional +from typing import Any, Dict, List, Optional, Union from pydantic import BaseModel, ConfigDict, Field, field_validator @@ -365,7 +365,12 @@ class MarketBriefForecast(BaseModel): point: Optional[float] = Field(default=None, description="Central forecast value") low: Optional[float] = Field(default=None, description="Lower bound of the forecast range") high: Optional[float] = Field(default=None, description="Upper bound of the forecast range") - confidence: Optional[str] = Field(default=None, description="Confidence label (e.g. high, medium, low)") + # The API historically sent a label ("high"/"medium"/"low") but now sends a + # numeric score (e.g. 0.65) — accept both. Caught by the live contract + # tests on 2026-07-03, first run with a real key. + confidence: Optional[Union[str, float]] = Field( + default=None, description="Confidence label (e.g. high) or numeric score (e.g. 0.65)" + ) class MarketBriefCommodity(BaseModel): diff --git a/tests/unit/test_subscriptions_resource.py b/tests/unit/test_subscriptions_resource.py index 35617b4..5f0edf5 100644 --- a/tests/unit/test_subscriptions_resource.py +++ b/tests/unit/test_subscriptions_resource.py @@ -219,3 +219,20 @@ def test_market_brief_narrative(self, client): _, kwargs = mock_req.call_args assert kwargs["params"]["codes"] == "WTI_USD,BRENT_CRUDE_USD" assert kwargs["params"]["narrative"] == "true" + + +class TestMarketBriefForecastConfidence: + """#2026-07-03 live-contract catch: API sends numeric confidence (0.65), + SDK previously required a string label — accept both.""" + + def test_confidence_accepts_float(self): + from oilpriceapi.models import MarketBriefForecast + + f = MarketBriefForecast(point=71.5, low=65.0, high=78.0, confidence=0.65) + assert f.confidence == 0.65 + + def test_confidence_accepts_label(self): + from oilpriceapi.models import MarketBriefForecast + + f = MarketBriefForecast(confidence="high") + assert f.confidence == "high"