commodutil 3.10.1__tar.gz → 4.0.1__tar.gz

commodutil-4.0.1/.gitignore

@@ -0,0 +1,27 @@
+/htmlcov/
+
+# Local IDE / agent state (should not be committed)
+.idea/
+.system/
+
+### Distribution / packaging
+build/
+dist/
+*.egg-info/
+.worktrees/
+
+### Byte-compiled
+__pycache__/
+*.py[cod]
+*.so
+
+### Test / coverage
+.pytest_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+
+### IDE
+.vscode/
+
+scripts/

{commodutil-3.10.1 → commodutil-4.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 3.10.1
+Version: 4.0.1
 Summary: common commodity/oil analytics utils
 Author-email: aeorxc <author@example.com>
 Project-URL: Homepage, https://dev.azure.com/RWEST-MFI-TE/Oil/_git/commodutil

{commodutil-3.10.1 → commodutil-4.0.1}/commodutil/__init__.py

@@ -25,16 +25,17 @@ _LAZY_EXPORTS = {
     "ALIASES": "commodutil.convfactors",
     "COMMODITIES": "commodutil.convfactors",
     "Commodity": "commodutil.convfactors",
-    "FRACTIONAL_TO_MAJOR": "commodutil.convfactors",
-    "VALID_CURRENCY_TOKENS": "commodutil.convfactors",
     "convert": "commodutil.convfactors",
     "convert_price": "commodutil.convfactors",
     "convfactor": "commodutil.convfactors",
-    "fractional_to_major": "commodutil.convfactors",
-    "is_fractional_currency": "commodutil.convfactors",
     "list_commodities": "commodutil.convfactors",
     "list_units": "commodutil.convfactors",
-    "split_currency_unit": "commodutil.convfactors",
+    # standards.currency (stdlib-only -- cheap, no pint)
+    "FRACTIONAL_TO_MAJOR": "commodutil.standards.currency",
+    "VALID_CURRENCY_TOKENS": "commodutil.standards.currency",
+    "fractional_to_major": "commodutil.standards.currency",
+    "is_fractional_currency": "commodutil.standards.currency",
+    "split_currency_unit": "commodutil.standards.currency",
     # dates
     "curmon": "commodutil.dates",
     "curmonyear": "commodutil.dates",

{commodutil-3.10.1 → commodutil-4.0.1}/commodutil/convfactors.py

@@ -11,6 +11,8 @@ from dataclasses import dataclass
 import pandas as pd
 from functools import lru_cache
 
+from commodutil.standards.units import to_pint_token as _to_pint_token
+
 logger = logging.getLogger(__name__)
 
 # Initialize pint with custom definitions
@@ -238,8 +240,8 @@ class CommodityConverter:
             convert(series, 'kt/month', 'bbl/day', commodity='gasoline')
         """
         # Normalize and parse units to handle daily/monthly rates
-        from_unit = self._normalize_unit(from_unit)
-        to_unit = self._normalize_unit(to_unit)
+        from_unit = _to_pint_token(from_unit)
+        to_unit = _to_pint_token(to_unit)
         from_rate = self._parse_rate_unit(from_unit)
         to_rate = self._parse_rate_unit(to_unit)
 
@@ -271,8 +273,8 @@ class CommodityConverter:
         self, value: float, from_unit: str, to_unit: str, commodity: Optional[str]
     ) -> float:
         """Convert a scalar value across mass/volume/energy using commodity context when needed."""
-        from_unit = self._normalize_unit(from_unit)
-        to_unit = self._normalize_unit(to_unit)
+        from_unit = _to_pint_token(from_unit)
+        to_unit = _to_pint_token(to_unit)
         qty = value * self.ureg(from_unit)
 
         # Try direct conversion first
@@ -402,10 +404,10 @@ class CommodityConverter:
         """Parse units like 'bbl/day' or 'kt/month'."""
         if "/" in unit:
             base, period = unit.split("/", 1)
-            base = self._normalize_unit(base)
+            base = _to_pint_token(base)
             period = period.strip().lower().rstrip("s")  # day(s), month(s), year(s)
             return {"base": base, "period": period}
-        return {"base": self._normalize_unit(unit), "period": None}
+        return {"base": _to_pint_token(unit), "period": None}
 
     def _rate_factor_scalar(
         self, from_period: Optional[str], to_period: Optional[str]
@@ -467,39 +469,6 @@ class CommodityConverter:
         except DimensionalityError:
             return False
 
-    def _normalize_unit(self, unit: str) -> str:
-        """Normalize common aliases and fix encoding issues.
-
-        - Map 'm��'/'m³'/'m**3'/'cubic_meter' -> 'm^3'
-        - Map energy aliases 'BTU' -> 'Btu', 'MMBTU' -> 'MMBtu'
-        - Trim whitespace
-        """
-        if unit is None:
-            return unit
-        u = unit.strip()
-        # Fix cubic meter notations and encoding issues
-        replacements = {
-            "m��": "m^3",
-            "m³": "m^3",
-            "m**3": "m^3",
-            "cubic_meter": "m^3",
-            "CUBIC_METER": "m^3",
-        }
-        for bad, good in replacements.items():
-            u = u.replace(bad, good)
-
-        # Additional robust normalizations using ASCII-only fallbacks
-        if u.lower() == "m3":
-            u = "m^3"
-        # Handle rate-style variants like 'm3/day' or 'M3/day'
-        u = u.replace("m3/", "m^3/").replace("M3/", "m^3/")
-        # Energy unit common uppercase forms
-        if u == "BTU":
-            u = "Btu"
-        if u == "MMBTU":
-            u = "MMBtu"
-        return u
-
     @property
     def available_commodities(self) -> list:
         """List all available commodities"""
@@ -567,28 +536,14 @@ def convfactor(from_unit: str, to_unit: str, commodity: Optional[str] = None) ->
 
 # ---- Currency-aware price conversion helpers ----
 #
-# Vocabulary moved to commodutil.standards.currency (2026-05) so it's
-# importable without dragging in pint / pandas. convfactors still owns the
-# integrated unit + currency `convert_price` math (which depends on the
-# pint registry above). Names are re-exported for backwards compatibility —
-# `from commodutil.convfactors import VALID_CURRENCY_TOKENS` still works.
+# Currency vocabulary lives in commodutil.standards.currency (importable
+# without dragging in pint / pandas). convfactors owns only the integrated
+# unit + currency `convert_price` math (which depends on the pint registry
+# above) and reads currency vocabulary directly from _currency. Callers
+# wanting currency vocabulary should import from commodutil.standards.currency.
 
 from commodutil.standards import currency as _currency
 
-_FRACTIONAL_CURRENCY_DIVISORS = _currency.FRACTIONAL_CURRENCY_DIVISORS
-_FRACTIONAL_TO_MAJOR = _currency.FRACTIONAL_TO_MAJOR
-_VALID_CURRENCY_TOKENS = _currency.VALID_CURRENCY_TOKENS
-
-# Public re-exports — preserve every existing public symbol so that
-# `from commodutil.convfactors import VALID_CURRENCY_TOKENS, fractional_to_major, ...`
-# continues to resolve for downstream packages (pyoilprice etc.).
-VALID_CURRENCY_TOKENS = _VALID_CURRENCY_TOKENS
-FRACTIONAL_TO_MAJOR = _FRACTIONAL_TO_MAJOR
-fractional_to_major = _currency.fractional_to_major
-is_fractional_currency = _currency.is_fractional_currency
-split_currency_unit = _currency.split_currency_unit
-_split_currency_unit = split_currency_unit
-
 
 def convert_price(
     value: Union[float, pd.Series],
@@ -648,15 +603,17 @@ def convert_price(
         fx_series = pd.Series([1.07, 1.08, 1.06], index=p.index)
         convert_price(p, 'EUR/MWh', 'USD/MMBtu', fx=fx_series)
     """
-    from_ccy, from_bare_unit = split_currency_unit(from_unit)
-    to_ccy, to_bare_unit = split_currency_unit(to_unit)
+    from_ccy, from_bare_unit = _currency.split_currency_unit(from_unit)
+    to_ccy, to_bare_unit = _currency.split_currency_unit(to_unit)
 
     # Resolve the underlying "major" currency on each side for same-base detection
     # (e.g. USc and USD share major USD — pure scale, no FX needed).
-    from_major = _FRACTIONAL_TO_MAJOR.get(
+    from_major = _currency.FRACTIONAL_TO_MAJOR.get(
         from_ccy, from_ccy.upper() if from_ccy else ""
     )
-    to_major = _FRACTIONAL_TO_MAJOR.get(to_ccy, to_ccy.upper() if to_ccy else "")
+    to_major = _currency.FRACTIONAL_TO_MAJOR.get(
+        to_ccy, to_ccy.upper() if to_ccy else ""
+    )
     # Treat '$' as 'USD' for the purpose of major-currency comparison.
     if from_major == "$":
         from_major = "USD"
@@ -685,8 +642,8 @@ def convert_price(
     # needed even though the literal currency tokens differ. Handle BEFORE the
     # `fx is None` raise below.
     if same_base_fractional:
-        from_div = _FRACTIONAL_CURRENCY_DIVISORS.get(from_ccy, 1.0)
-        to_div = _FRACTIONAL_CURRENCY_DIVISORS.get(to_ccy, 1.0)
+        from_div = _currency.FRACTIONAL_CURRENCY_DIVISORS.get(from_ccy, 1.0)
+        to_div = _currency.FRACTIONAL_CURRENCY_DIVISORS.get(to_ccy, 1.0)
         # value is in source-currency units; divide by from_div to get majors,
         # multiply by to_div to get target-currency units.
         return unit_converted * (to_div / from_div)
@@ -702,7 +659,7 @@ def convert_price(
             f"(source currency '{from_ccy}' is non-USD)"
         )
 
-    fractional_divisor = _FRACTIONAL_CURRENCY_DIVISORS.get(from_ccy, 1.0)
+    fractional_divisor = _currency.FRACTIONAL_CURRENCY_DIVISORS.get(from_ccy, 1.0)
 
     if isinstance(unit_converted, pd.Series) and isinstance(fx, pd.Series):
         target_idx = unit_converted.index
@@ -774,7 +731,7 @@ def list_commodities():
 def list_units():
     """List common units"""
     # Return normalized forms to avoid encoding issues
-    return [converter._normalize_unit(u) for u in converter.available_units]
+    return [_to_pint_token(u) for u in converter.available_units]
 
 
 # Example usage

{commodutil-3.10.1 → commodutil-4.0.1}/commodutil/standards/__init__.py

@@ -12,6 +12,9 @@ from commodutil.standards.analysis_types import (
 from commodutil.standards.commodities import (
     COMMODITY_CONVERSION_MAP,
     COMMODITY_KEYWORDS,
+    infer_commodity_and_group,
+    infer_commodity_from_exchange_symbol,
+    normalize_commodity_for_conversion,
 )
 from commodutil.standards.commodity_groups import (
     COMMODITY_GROUPS,
@@ -19,6 +22,7 @@ from commodutil.standards.commodity_groups import (
     is_valid_commodity_group,
 )
 from commodutil.standards.currency import (
+    CURRENCY_MAP,
     FRACTIONAL_CURRENCY_DIVISORS,
     FRACTIONAL_TO_MAJOR,
     VALID_CURRENCY_TOKENS,
@@ -29,14 +33,18 @@ from commodutil.standards.currency import (
     to_symbol,
 )
 from commodutil.standards.regions import (
+    CRUDE_GRADE_REGIONS,
     REGION_PATTERNS,
+    VALID_CRUDE_GRADE_REGIONS,
     VALID_REGIONS,
+    is_crude_grade_region,
     is_valid_region,
     normalize_region,
 )
 from commodutil.standards.units import (
     UNIT_MAP,
     default_unit_for_commodity,
+    to_pint_token,
 )
 
 __all__ = [
@@ -46,11 +54,15 @@ __all__ = [
     # commodities
     "COMMODITY_CONVERSION_MAP",
     "COMMODITY_KEYWORDS",
+    "infer_commodity_and_group",
+    "infer_commodity_from_exchange_symbol",
+    "normalize_commodity_for_conversion",
     # commodity_groups
     "COMMODITY_GROUPS",
     "VALID_COMMODITY_GROUPS",
     "is_valid_commodity_group",
     # currency
+    "CURRENCY_MAP",
     "FRACTIONAL_CURRENCY_DIVISORS",
     "FRACTIONAL_TO_MAJOR",
     "VALID_CURRENCY_TOKENS",
@@ -60,11 +72,15 @@ __all__ = [
     "split_currency_unit",
     "to_symbol",
     # regions
+    "CRUDE_GRADE_REGIONS",
     "REGION_PATTERNS",
+    "VALID_CRUDE_GRADE_REGIONS",
     "VALID_REGIONS",
+    "is_crude_grade_region",
     "is_valid_region",
     "normalize_region",
     # units
     "UNIT_MAP",
     "default_unit_for_commodity",
+    "to_pint_token",
 ]

commodutil-4.0.1/commodutil/standards/commodities.py

@@ -0,0 +1,208 @@
+"""commodutil.standards.commodities: canonical commodity vocabulary.
+
+Owns:
+- COMMODITY_KEYWORDS: ordered list of (display_name, group, [keywords])
+  used by free-text inference. Ordering matters — "Natural Gasoline"
+  must precede "Natural Gas" so the substring "natural gas" inside
+  "natural gasoline" doesn't win.
+- COMMODITY_CONVERSION_MAP: display_name -> commodutil.convfactors.COMMODITIES
+  key, for downstream conversion routing.
+- infer_commodity_and_group(text): free-text inference helper that walks
+  COMMODITY_KEYWORDS in order and returns the first hit.
+- normalize_commodity_for_conversion(commodity): map a free-form commodity
+  string to a commodutil.convfactors conversion key.
+- infer_commodity_from_exchange_symbol(symbol): last-resort short-substring
+  fallback for raw exchange symbols (e.g. "CL_Mar25" -> "crude").
+
+Previously lived in curvemetadata.common_maps / curvemetadata.taxonomy;
+relocated to eliminate divergence risk between curvemetadata and
+commodutil's commodity lists.
+"""
+
+from __future__ import annotations
+
+
+COMMODITY_KEYWORDS = [
+    ("Brent", "Crude Oil", ["brent"]),
+    ("WTI", "Crude Oil", ["wti"]),
+    ("Crude Oil", "Crude Oil", ["crude oil", "crude"]),
+    # NB: 'Natural Gasoline' MUST come before 'Natural Gas' — the substring
+    # "natural gas" is contained in "natural gasoline" and would otherwise win.
+    ("Natural Gasoline", "NGL", ["natural gasoline"]),
+    ("Natural Gas", "Natural Gas", ["natural gas", "nat gas", "natgas"]),
+    ("Jet", "Refined Products", ["jet fuel", "jet"]),
+    ("Diesel", "Refined Products", ["diesel", "ulsd", "gasoil", "heating oil"]),
+    ("Gasoline", "Refined Products", ["gasoline", "rbob", "cbob", "mogas", "eurobob"]),
+    ("Fuel Oil", "Refined Products", ["fuel oil", "hsfo", "lsfo", "marine fuel"]),
+    ("Naphtha", "Refined Products", ["naphtha"]),
+    ("Product Basket", "Refined Products", ["refined products", "product basket"]),
+    ("VGO", "Refined Products", ["vgo"]),
+    ("FAME", "Biofuel", ["fame"]),
+    ("HVO", "Biofuel", ["hvo"]),
+    ("Isobutane", "NGL", ["isobutane"]),
+    ("Butane", "NGL", ["butane"]),
+    ("Ethane", "NGL", ["ethane"]),
+    ("Propane", "NGL", ["propane"]),
+    ("NGL", "NGL", ["ngl"]),
+    ("FFA", "Freight", ["freight", "ffa"]),
+]
+
+COMMODITY_CONVERSION_MAP = {
+    "Crude Oil": "crude",
+    "Brent": "crude",
+    "WTI": "crude",
+    "Natural Gas": "natgas",
+    "Jet": "jet",
+    "Diesel": "diesel",
+    "Gasoline": "gasoline",
+    "Fuel Oil": "fuel_oil",
+    "Naphtha": "naphtha",
+    "Product Basket": "product_basket",
+    "VGO": "vgo",
+    "FAME": "fame",
+    "HVO": "hvo",
+    # NGL species — switched from the generic 'lpg' blend to first-class species
+    # in commodutil 2026-05 (each has its own density / HHV for $/gal<->$/MMBtu).
+    # Keep the generic 'NGL' bucket on 'lpg' as a safe blend default.
+    "Natural Gasoline": "natural_gasoline",
+    "Isobutane": "isobutane",
+    "Butane": "butane",
+    "Propane": "propane",
+    "NGL": "lpg",
+    "Ethane": "ethane",
+}
+
+
+def _normalize_text(value: str) -> str:
+    """Normalise text for keyword matching: lowercase, replace separators, collapse whitespace.
+
+    Args:
+        value: Input text string.
+
+    Returns:
+        Normalised lowercase text with single spaces and no `/` or `-` separators.
+    """
+    text = value.strip().lower()
+    text = text.replace("/", " ").replace("-", " ")
+    text = " ".join(text.split())
+    return text
+
+
+def infer_commodity_and_group(
+    text: Optional[str],
+) -> tuple[Optional[str], Optional[str]]:
+    """Infer commodity and group from free-form text using COMMODITY_KEYWORDS.
+
+    Args:
+        text: Product name or description text.
+
+    Returns:
+        Tuple of (commodity_name, group_name), or (None, None) if not found.
+
+    Examples:
+        >>> infer_commodity_and_group("ICE Brent Crude Futures")
+        ('Brent', 'Crude Oil')
+        >>> infer_commodity_and_group("Henry Hub Natural Gas")
+        ('Natural Gas', 'Natural Gas')
+        >>> infer_commodity_and_group("Natural Gasoline OPIS")
+        ('Natural Gasoline', 'NGL')
+        >>> infer_commodity_and_group("Unknown Widget") == (None, None)
+        True
+    """
+    if not text:
+        return None, None
+    haystack = _normalize_text(str(text))
+    for commodity_name, group_name, keywords in COMMODITY_KEYWORDS:
+        for keyword in keywords:
+            if keyword in haystack:
+                return commodity_name, group_name
+    return None, None
+
+
+def normalize_commodity_for_conversion(commodity: Optional[str]) -> Optional[str]:
+    """Normalise a free-form commodity string to a commodutil conversion key.
+
+    Args:
+        commodity: Commodity name (free-form text or canonical display name).
+
+    Returns:
+        Normalised key for use with commodutil.convfactors conversion
+        functions (e.g. ``"crude"``, ``"natgas"``), or ``None`` for empty
+        input. Falls back to a slugged form of the input if no
+        COMMODITY_KEYWORDS hit.
+
+    Examples:
+        >>> normalize_commodity_for_conversion("Brent")
+        'crude'
+        >>> normalize_commodity_for_conversion("ICE Brent Crude")
+        'crude'
+        >>> normalize_commodity_for_conversion(None) is None
+        True
+    """
+    if not commodity:
+        return None
+
+    text = _normalize_text(str(commodity))
+
+    commodity_name, _ = infer_commodity_and_group(text)
+    if commodity_name:
+        mapped = COMMODITY_CONVERSION_MAP.get(commodity_name)
+        if mapped:
+            return mapped
+        return _normalize_text(commodity_name).replace(" ", "_")
+
+    return text.replace(" ", "_")
+
+
+def infer_commodity_from_exchange_symbol(symbol: Optional[str]) -> Optional[str]:
+    """Infer commodity from a raw exchange symbol name (loose substring match).
+
+    Last-resort fallback when description-based ``infer_commodity_and_group``
+    fails (no Description, or Description didn't match COMMODITY_KEYWORDS).
+    Mirrors legacy substring-fallback logic that lived inline in
+    ``pyoilprice.conversion`` and then in ``curvemetadata.taxonomy``. Patterns
+    are SHORT substrings (cl, rb, ho, ng) matched anywhere in the input —
+    ``"close_value"`` will match ``cl`` and return ``"crude"``. This is
+    acceptable on raw exchange-symbol identifiers (which are short and
+    predictable) but **UNSAFE on free-text inputs** — use
+    ``infer_commodity_and_group()`` for descriptions or product names.
+
+    Returns:
+        Canonical commodity name ('crude' / 'gasoline' / 'gasoil' / 'natgas')
+        or None if no match.
+
+    Examples (raw exchange symbols only):
+        >>> infer_commodity_from_exchange_symbol("CL_Mar25")
+        'crude'
+        >>> infer_commodity_from_exchange_symbol("ICE_EuroFutures:BRN")
+        'crude'
+        >>> infer_commodity_from_exchange_symbol("RBOB_Apr25")
+        'gasoline'
+        >>> infer_commodity_from_exchange_symbol("HO_May25")
+        'gasoil'
+        >>> infer_commodity_from_exchange_symbol("NG_Jun25")
+        'natgas'
+        >>> infer_commodity_from_exchange_symbol("XYZ_Spot") is None
+        True
+    """
+    if not symbol:
+        return None
+    s = str(symbol).lower()
+    if any(x in s for x in ["cl", "wti", "brent", "brn"]):
+        return "crude"
+    if any(x in s for x in ["rb", "gasoline", "mogas"]):
+        return "gasoline"
+    if any(x in s for x in ["ho", "diesel", "gasoil"]):
+        return "gasoil"
+    if any(x in s for x in ["ng", "natural"]):
+        return "natgas"
+    return None
+
+
+__all__ = [
+    "COMMODITY_KEYWORDS",
+    "COMMODITY_CONVERSION_MAP",
+    "infer_commodity_and_group",
+    "normalize_commodity_for_conversion",
+    "infer_commodity_from_exchange_symbol",
+]

{commodutil-3.10.1 → commodutil-4.0.1}/commodutil/standards/currency.py

@@ -210,10 +210,36 @@ def to_symbol(code: Optional[str]) -> str:
     return _SYMBOLS.get(str(code), str(code))
 
 
+# ---- Vendor-spec free-text -> canonical-token map ------------------------
+#
+# Maps lowercase free-form currency phrases (as they appear in CME/ICE
+# contract spec descriptions) to canonical ISO 4217 codes. Used by
+# vendor-spec parsers (e.g. curvemetadata.ice_util.map_currency) to lift
+# strings like "US Dollars and Cents" -> "USD". Keys are matched
+# case-insensitively at call time — callers should lowercase input.
+#
+# Lifted from curvemetadata.common_maps so commodutil owns the single
+# source of truth for currency-token vocabulary.
+CURRENCY_MAP = {
+    "us dollars and cents": "USD",
+    "u.s. dollars and cents": "USD",
+    "us dollars": "USD",
+    "u.s. dollars": "USD",
+    "usd": "USD",
+    "euros": "EUR",
+    "euro": "EUR",
+    "pounds sterling": "GBP",
+    "british pounds": "GBP",
+    "canadian dollars": "CAD",
+    "cad": "CAD",
+}
+
+
 __all__ = [
     "VALID_CURRENCY_TOKENS",
     "FRACTIONAL_TO_MAJOR",
     "FRACTIONAL_CURRENCY_DIVISORS",
+    "CURRENCY_MAP",
     "is_fractional_currency",
     "fractional_to_major",
     "split_currency_unit",

{commodutil-3.10.1 → commodutil-4.0.1}/commodutil/standards/regions.py

@@ -29,6 +29,8 @@ REGION_PATTERNS = [
     ("ARA", ["ara"]),
     ("Med", ["mediterranean", "med"]),
     ("Sing", ["singapore", "sing"]),
+    ("MEG", ["meg", "middle east gulf", "arabian gulf", "persian gulf"]),
+    ("Japan", ["japan"]),
 ]
 
 # Canonical region codes as frozenset for fast membership checks
@@ -97,9 +99,109 @@ def is_valid_region(code: str) -> bool:
     return code in VALID_REGIONS
 
 
+# ---- Crude grade regions ----
+#
+# Producer-region groupings for crude grades, used by crude-differentials
+# charts. Lifted from oilpricingcharts.symbols_config_crudediffs (keys kept
+# byte-identical to the source so chart configs can switch over without
+# re-mapping). Values are ordered tuples of display grade names — they are
+# NOT pricing symbols and do NOT carry vendor (Platts/Argus) IDs. Symbol
+# resolution stays in the chart-config layer.
+CRUDE_GRADE_REGIONS = {
+    "north_sea": (
+        "Forties",
+        "Oseberg",
+        "Ekofisk",
+        "Troll",
+        "Johan Sverdrup",
+        "FOB N Sea WTI Midland",
+    ),
+    "waf": (
+        "Bonny Light",
+        "Forcados",
+        "Qua Iboe",
+        "Cabinda",
+        "Doba",
+    ),
+    "nafrica": (
+        "Nile Blend",
+        "Dar Blend",
+        "Es Sider",
+    ),
+    "russian": (
+        "Urals Rott",
+        "Urals Med",
+        "ESPO",
+        "Siberian Light",
+        "Sokol",
+    ),
+    "us_midcon": (
+        "Bakken Clearbook",
+        "Light Sweet Guernsey",
+        "Denver Julesburg Light",
+    ),
+    "us_texas": (
+        "WTI Houston",
+        "WTI Midland",
+        "WTS",
+        "Southern Green Canyon",
+        "WCS Houston",
+    ),
+    "us_louisiana": (
+        "LLS",
+        "HLS",
+        "Thunder Horse",
+        "Poseidon",
+        "Mars",
+    ),
+    "canadian": (
+        "WCS",
+        "CDB",
+        "AWB",
+        "CLK",
+        "MSW",
+        "Syn",
+    ),
+    "latam_wti": (
+        "Vasconia",
+        "Castilla",
+        "Maya",
+        "Liza",
+        "Buzios",
+        "Mero",
+        "Tupi",
+        "Unity Gold",
+    ),
+    "asia_pacific": (
+        "Tapis",
+        "Duri",
+        "Vincent",
+    ),
+    "middle_east": (
+        "Dubai",
+        "Oman",
+        "Murban",
+        "Al Shaheen",
+        "Upper Zakum",
+        "Qatar Land",
+        "Qatar Marine",
+    ),
+}
+
+VALID_CRUDE_GRADE_REGIONS = frozenset(CRUDE_GRADE_REGIONS.keys())
+
+
+def is_crude_grade_region(key: str) -> bool:
+    """Return True if key is a canonical crude grade-region key."""
+    return key in VALID_CRUDE_GRADE_REGIONS
+
+
 __all__ = [
     "REGION_PATTERNS",
     "VALID_REGIONS",
     "normalize_region",
     "is_valid_region",
+    "CRUDE_GRADE_REGIONS",
+    "VALID_CRUDE_GRADE_REGIONS",
+    "is_crude_grade_region",
 ]