commodutil 3.9.0__tar.gz → 3.10.0__tar.gz

{commodutil-3.9.0 → commodutil-3.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 3.9.0
+Version: 3.10.0
 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.0/commodutil/__init__.py

@@ -0,0 +1,80 @@
+"""commodutil: Commodity market standards backbone.
+
+Public API for unit conversions, forward curve transforms, date utilities,
+and pandas helpers. Symbols are loaded lazily on first access via PEP 562
+`__getattr__` so `import commodutil` stays cheap (~10ms vs. ~3s if the
+facade eagerly imported convfactors and its pint registry).
+
+Cheap paths:
+    import commodutil                                  # near-instant
+    from commodutil.standards.regions import ...       # stdlib only
+    from commodutil.standards.currency import ...      # stdlib only
+
+Heavier paths (lazy-load their sub-module on first attribute access):
+    from commodutil import convert_price               # triggers convfactors
+    from commodutil import curyear                     # triggers dates
+"""
+
+from __future__ import annotations
+
+# Map exported name -> dotted submodule path. Single source of truth for the
+# public facade. Keys in this dict are what `from commodutil import X` will
+# resolve via __getattr__ below.
+_LAZY_EXPORTS = {
+    # convfactors (heaviest -- pint registry + Commodity dataclass init)
+    "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",
+    # dates
+    "curmon": "commodutil.dates",
+    "curmonyear": "commodutil.dates",
+    "curmonyear_str": "commodutil.dates",
+    "curyear": "commodutil.dates",
+    "find_year": "commodutil.dates",
+    "last_day_of_prev_month": "commodutil.dates",
+    "nextyear": "commodutil.dates",
+    "prevmon": "commodutil.dates",
+    "prevmon_str": "commodutil.dates",
+    "prevyear": "commodutil.dates",
+    "start_day_of_prev_month": "commodutil.dates",
+    # forwards
+    "all_spread_combinations": "commodutil.forwards",
+    "time_spreads": "commodutil.forwards",
+    # pandasutil
+    "fillna_downbet": "commodutil.pandasutil",
+    "mergets": "commodutil.pandasutil",
+    # transforms
+    "seasonalize": "commodutil.transforms",
+}
+
+__all__ = sorted(_LAZY_EXPORTS.keys())
+
+
+def __getattr__(name: str):
+    """PEP 562 lazy attribute access — loads the source submodule on first
+    use of a facade-exported symbol, caches the resolved value back into
+    the module's globals so subsequent accesses skip the dispatch.
+    """
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module 'commodutil' has no attribute {name!r}")
+    import importlib
+
+    module = importlib.import_module(module_path)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))

commodutil-3.10.0/commodutil/standards/analysis_types.py

@@ -0,0 +1,59 @@
+"""commodutil.standards.analysis_types: canonical analysis-type vocabulary.
+
+Owns the inference function for classifying a curve as one of:
+- 'crack': cracking spread
+- 'arb': geographic arbitrage spread
+- 'diff': differential / generic spread
+- 'outright': none of the above (flat price)
+
+Previously duplicated in curvemetadata.ice._infer_analysis_type (substring
+matching) and curvemetadata.cme._infer_analysis_type (regex word-boundary).
+Consolidated here using the stricter regex approach -- substring 'crack' in
+'crackers' would have been a false positive in the ICE version.
+
+Future subtypes (hi5, regrade, freight) are NOT included in this round --
+they require validation against actual Curve.Definitions.Analysis values
+in MetadataDB2, which is a separate piece of work.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# Closed set of types recognised by infer_analysis_type. Callers downstream
+# may treat the return as a canonical tag.
+ANALYSIS_TYPES = ("crack", "arb", "diff", "outright")
+
+
+def infer_analysis_type(
+    text: Optional[str],
+    extra_text: Optional[str] = None,
+    category: Optional[str] = None,
+) -> str:
+    """Infer analysis type from product metadata.
+
+    Returns one of: 'crack', 'arb', 'diff', 'outright'. Defaults to
+    'outright' when no pattern matches.
+
+    Args:
+        text: Primary product name or description.
+        extra_text: Optional secondary text (e.g. CME sub-category) --
+            appended to `text` for matching.
+        category: Optional explicit category field. If equals 'arb'
+            (case-insensitive), short-circuits to 'arb' regardless of
+            other text content (CME convention).
+    """
+    if isinstance(category, str) and category.strip().lower() == "arb":
+        return "arb"
+    combined = f"{text or ''} {extra_text or ''}".lower()
+    if re.search(r"\bcrack\b", combined):
+        return "crack"
+    if re.search(r"\barb\b", combined):
+        return "arb"
+    if re.search(r"\bdiff\b", combined) or re.search(r"\bspread\b", combined):
+        return "diff"
+    return "outright"
+
+
+__all__ = ["ANALYSIS_TYPES", "infer_analysis_type"]

commodutil-3.10.0/commodutil/standards/commodities.py

@@ -0,0 +1,71 @@
+"""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.
+
+Previously lived in curvemetadata.common_maps; relocated to eliminate
+divergence risk between curvemetadata and commodutil's commodity lists.
+curvemetadata.common_maps re-exports for backwards compatibility.
+"""
+
+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",
+}
+
+__all__ = [
+    "COMMODITY_KEYWORDS",
+    "COMMODITY_CONVERSION_MAP",
+]

commodutil-3.10.0/commodutil/standards/commodity_groups.py

@@ -0,0 +1,40 @@
+"""commodutil.standards.commodity_groups: canonical commodity group taxonomy.
+
+Mirrors the CommodityGroup CHECK constraint on Curve.Definitions in
+MetadataDB2 (see curvemetadata/sql/001_create_curvemetadata_tables.sql).
+Single source of truth for the Python side -- curvemetadata.ice and
+curvemetadata.cme currently hard-code these strings; they can adopt
+this constant in a follow-up.
+"""
+
+from __future__ import annotations
+
+# Ordered to match the SQL constraint order (preserves what consumers see
+# when iterating). Treat as a closed set -- additions require a coordinated
+# SQL migration.
+COMMODITY_GROUPS = (
+    "Agriculture",
+    "Biofuel",
+    "Crude Oil",
+    "Freight",
+    "LNG",
+    "Natural Gas",
+    "NGL",
+    "Petrochemical",
+    "Refined Products",
+)
+
+# Set for O(1) membership checks
+VALID_COMMODITY_GROUPS = frozenset(COMMODITY_GROUPS)
+
+
+def is_valid_commodity_group(value: str) -> bool:
+    """Return True if `value` is a recognised commodity group string."""
+    return value in VALID_COMMODITY_GROUPS
+
+
+__all__ = [
+    "COMMODITY_GROUPS",
+    "VALID_COMMODITY_GROUPS",
+    "is_valid_commodity_group",
+]

commodutil-3.10.0/commodutil/standards/units.py

@@ -0,0 +1,64 @@
+"""commodutil.standards.units: canonical unit vocabulary.
+
+Owns:
+- UNIT_MAP: alias -> canonical unit map for normalising free-form unit
+  strings from vendor contract specs ("barrel", "Barrels", "BBL" -> "bbl").
+- default_unit_for_commodity(): returns the canonical quoted unit for a
+  commodity (volume basis).
+
+Pure vocab -- no pint, no pandas. The pint registry in
+commodutil.convfactors handles unit algebra; this module handles the
+string-normalisation layer that runs BEFORE algebra.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+# ---- Alias -> canonical normalisation ----
+
+# Maps lowercase aliases (singular / plural / abbreviated forms) to the
+# canonical unit token used by downstream code. Used by vendor-spec
+# parsers (e.g. curvemetadata.ice_util.parse_unit). Keys are matched
+# case-insensitively at call time -- callers should lowercase input.
+UNIT_MAP = {
+    "barrel": "bbl",
+    "barrels": "bbl",
+    "bbl": "bbl",
+    "bbls": "bbl",
+    "gallon": "gal",
+    "gallons": "gal",
+    "gal": "gal",
+    "metric ton": "mt",
+    "metric tons": "mt",
+    "metric tonne": "mt",
+    "metric tonnes": "mt",
+    "tonne": "mt",
+    "tonnes": "mt",
+}
+
+
+# ---- Default unit per commodity ----
+
+_DEFAULT_UNIT = {
+    "natgas": "mmbtu",
+    "natural_gas": "mmbtu",
+    "gasoline": "gal",
+    "diesel": "gal",
+    "jet": "gal",
+}
+
+
+def default_unit_for_commodity(commodity: Optional[str]) -> str:
+    """Return the canonical quoted unit for a commodity (volume basis).
+
+    Falls back to 'bbl' for any commodity not in the explicit map (covers
+    crude / fuel oil / naphtha / VGO / NGL species etc.).
+    """
+    if not commodity:
+        return "bbl"
+    return _DEFAULT_UNIT.get(str(commodity).lower(), "bbl")
+
+
+__all__ = ["UNIT_MAP", "default_unit_for_commodity"]

{commodutil-3.9.0 → commodutil-3.10.0}/commodutil.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 3.9.0
+Version: 3.10.0
 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.9.0 → commodutil-3.10.0}/commodutil.egg-info/SOURCES.txt

@@ -32,6 +32,9 @@ commodutil/forward/spreads.py
 commodutil/forward/structure.py
 commodutil/forward/util.py
 commodutil/standards/__init__.py
+commodutil/standards/analysis_types.py
+commodutil/standards/commodities.py
+commodutil/standards/commodity_groups.py
 commodutil/standards/currency.py
 commodutil/standards/regions.py
 commodutil/standards/units.py
@@ -45,6 +48,9 @@ tests/test_dates.py
 tests/test_forwards.py
 tests/test_pandasutils.py
 tests/test_price_conv.py
+tests/test_standards_analysis_types.py
+tests/test_standards_commodities.py
+tests/test_standards_commodity_groups.py
 tests/test_standards_currency.py
 tests/test_standards_regions.py
 tests/test_standards_units.py

commodutil-3.10.0/tests/test_standards_analysis_types.py

@@ -0,0 +1,60 @@
+"""Tests for commodutil.standards.analysis_types."""
+
+from commodutil.standards.analysis_types import ANALYSIS_TYPES, infer_analysis_type
+
+
+def test_recognises_crack():
+    assert infer_analysis_type("Brent-Diesel Crack") == "crack"
+    assert infer_analysis_type("WTI Crack Spread") == "crack"
+
+
+def test_recognises_arb():
+    assert infer_analysis_type("Singapore-LA Gasoline Arb") == "arb"
+
+
+def test_recognises_diff():
+    assert infer_analysis_type("Brent-WTI Diff") == "diff"
+    assert infer_analysis_type("Gasoil-Heating Oil Spread") == "diff"
+
+
+def test_default_outright():
+    assert infer_analysis_type("Brent Front Month") == "outright"
+    assert infer_analysis_type("WTI Cushing") == "outright"
+
+
+def test_empty_and_none():
+    assert infer_analysis_type("") == "outright"
+    assert infer_analysis_type(None) == "outright"
+
+
+def test_word_boundary_prevents_false_match():
+    """Substring matching (old ICE behavior) would have wrongly returned
+    'crack' for 'crackers' or 'arb' for 'arbitrary'. Word boundary fixes."""
+    assert infer_analysis_type("crackers party") == "outright"
+    assert infer_analysis_type("arbitrary value") == "outright"
+    assert infer_analysis_type("trackers") == "outright"
+
+
+def test_category_short_circuit():
+    # CME convention: category="arb" wins regardless of text
+    assert infer_analysis_type("WTI Front Month", category="arb") == "arb"
+    assert infer_analysis_type("WTI Front Month", category="ARB") == "arb"
+    # Other category values don't override
+    assert infer_analysis_type("WTI Brent Diff", category="energy") == "diff"
+
+
+def test_extra_text_appended():
+    # ICE-style single-arg call still works (extra_text defaults to None)
+    assert infer_analysis_type("WTI Crack Spread") == "crack"
+    # CME-style multi-arg: sub_category contributes
+    assert infer_analysis_type("WTI Brent", "crack") == "crack"
+    assert infer_analysis_type("WTI Brent", None, None) == "outright"
+
+
+def test_crack_priority_over_arb_diff():
+    """Order matters: crack short-circuits before arb/diff checks."""
+    assert infer_analysis_type("Gasoline Crack Arb") == "crack"
+
+
+def test_analysis_types_constant():
+    assert ANALYSIS_TYPES == ("crack", "arb", "diff", "outright")

commodutil-3.10.0/tests/test_standards_commodities.py

@@ -0,0 +1,71 @@
+"""Tests for commodutil.standards.commodities."""
+
+from __future__ import annotations
+
+import pytest
+
+from commodutil.standards.commodities import (
+    COMMODITY_CONVERSION_MAP,
+    COMMODITY_KEYWORDS,
+)
+
+
+def test_commodity_keywords_sanity_length():
+    assert len(COMMODITY_KEYWORDS) >= 20
+
+
+def test_commodity_keywords_entry_shape():
+    for entry in COMMODITY_KEYWORDS:
+        assert isinstance(entry, tuple)
+        assert len(entry) == 3
+        display, group, kws = entry
+        assert isinstance(display, str)
+        assert isinstance(group, str)
+        assert isinstance(kws, list)
+        assert all(isinstance(k, str) for k in kws)
+
+
+def test_natural_gasoline_before_natural_gas():
+    displays = [d for d, _, _ in COMMODITY_KEYWORDS]
+    assert "Natural Gasoline" in displays
+    assert "Natural Gas" in displays
+    assert displays.index("Natural Gasoline") < displays.index("Natural Gas")
+
+
+def test_brent_entry_present():
+    assert ("Brent", "Crude Oil", ["brent"]) in COMMODITY_KEYWORDS
+
+
+def test_conversion_map_brent_is_crude():
+    assert COMMODITY_CONVERSION_MAP["Brent"] == "crude"
+
+
+def test_conversion_map_natural_gas_is_natgas():
+    assert COMMODITY_CONVERSION_MAP["Natural Gas"] == "natgas"
+
+
+def test_conversion_map_ngl_default_lpg_blend():
+    assert COMMODITY_CONVERSION_MAP["NGL"] == "lpg"
+
+
+def test_conversion_map_no_orphan_entries():
+    """Every commodity in COMMODITY_CONVERSION_MAP appears as a display_name
+    in COMMODITY_KEYWORDS — consistency check."""
+    displays = {d for d, _, _ in COMMODITY_KEYWORDS}
+    orphans = set(COMMODITY_CONVERSION_MAP.keys()) - displays
+    assert not orphans, f"Orphan conversion map entries: {orphans}"
+
+
+def test_parity_with_curvemetadata():
+    """Verify COMMODITY_KEYWORDS / COMMODITY_CONVERSION_MAP are identical to
+    the curvemetadata copies — guards against divergence during the migration."""
+    try:
+        from curvemetadata.common_maps import (
+            COMMODITY_CONVERSION_MAP as cm_MAP,
+            COMMODITY_KEYWORDS as cm_KW,
+        )
+    except ImportError:
+        pytest.skip("curvemetadata not available")
+
+    assert COMMODITY_KEYWORDS == cm_KW
+    assert COMMODITY_CONVERSION_MAP == cm_MAP

commodutil-3.10.0/tests/test_standards_commodity_groups.py

@@ -0,0 +1,93 @@
+"""Tests for commodutil.standards.commodity_groups."""
+
+from __future__ import annotations
+
+import pytest
+
+from commodutil.standards.commodity_groups import (
+    COMMODITY_GROUPS,
+    VALID_COMMODITY_GROUPS,
+    is_valid_commodity_group,
+)
+
+
+EXPECTED_GROUPS = (
+    "Agriculture",
+    "Biofuel",
+    "Crude Oil",
+    "Freight",
+    "LNG",
+    "Natural Gas",
+    "NGL",
+    "Petrochemical",
+    "Refined Products",
+)
+
+
+def test_count_is_nine():
+    assert len(COMMODITY_GROUPS) == 9
+
+
+def test_exact_tuple_equality_preserves_sql_order():
+    # COMMODITY_GROUPS docstring promises SQL constraint order is preserved.
+    # A future maintainer reordering the tuple would silently change what
+    # downstream consumers see when iterating.
+    assert COMMODITY_GROUPS == EXPECTED_GROUPS
+
+
+def test_valid_set_matches_expected():
+    assert VALID_COMMODITY_GROUPS == frozenset(EXPECTED_GROUPS)
+
+
+def test_all_expected_groups_present():
+    for group in EXPECTED_GROUPS:
+        assert group in VALID_COMMODITY_GROUPS, f"Missing: {group}"
+
+
+def test_is_valid_crude_oil():
+    assert is_valid_commodity_group("Crude Oil") is True
+
+
+def test_is_valid_case_sensitive():
+    # Matches SQL semantics -- the CHECK constraint uses exact-cased
+    # N'Crude Oil' literals.
+    assert is_valid_commodity_group("crude oil") is False
+
+
+def test_is_valid_unknown_returns_false():
+    assert is_valid_commodity_group("Unknown") is False
+
+
+def test_is_valid_empty_string_returns_false():
+    assert is_valid_commodity_group("") is False
+
+
+def test_commodity_groups_is_tuple():
+    assert isinstance(COMMODITY_GROUPS, tuple)
+
+
+def test_valid_commodity_groups_is_frozenset():
+    assert isinstance(VALID_COMMODITY_GROUPS, frozenset)
+
+
+# Cross-check: every CommodityGroup string used by curvemetadata.cme and
+# curvemetadata.ice must round-trip through VALID_COMMODITY_GROUPS. If
+# curvemetadata adds a new group string before the SQL constraint is
+# extended, this test flags the divergence loudly.
+CURVEMETADATA_USED_GROUPS = (
+    "Crude Oil",
+    "Refined Products",
+    "Petrochemical",
+    "Freight",
+    "NGL",
+    "Biofuel",
+    # Natural Gas / LNG / Agriculture are not currently used by ice.py /
+    # cme.py but are reserved by the SQL constraint.
+)
+
+
+@pytest.mark.parametrize("group", CURVEMETADATA_USED_GROUPS)
+def test_curvemetadata_group_is_recognised(group):
+    assert is_valid_commodity_group(group), (
+        f"curvemetadata uses {group!r} but it is not in VALID_COMMODITY_GROUPS"
+    )

{commodutil-3.9.0 → commodutil-3.10.0}/tests/test_standards_regions.py

@@ -102,10 +102,12 @@ def test_parity_with_curvemetadata_long_patterns_only():
         )
 
 
-def test_short_pattern_divergence_from_curvemetadata():
-    """Pin the known bug fix: normalize_region matches short codes that
-    curvemetadata.infer_region (broken) does not. If curvemetadata ever
-    fixes its `\\b` typo, this test will fail and should be deleted.
+def test_short_pattern_parity_with_curvemetadata():
+    """Short-pattern (len <= 3) regions used to diverge between
+    normalize_region and curvemetadata.taxonomy.infer_region because
+    the latter had a `\\b` regex bug (literal backslash-b instead of
+    a word boundary). The bug was fixed in curvemetadata 2026-05;
+    this test is now a regression guard against the bug returning.
     """
     try:
         from curvemetadata.taxonomy import infer_region
@@ -114,27 +116,29 @@ def test_short_pattern_divergence_from_curvemetadata():
 
         pytest.skip("curvemetadata not available in this environment")
 
-    # Only patterns of len <= 3 hit the broken regex branch. Among the
-    # configured patterns those are: "nyh", "ara", "med", "nwe".
+    # Only patterns of len <= 3 hit the previously-broken regex branch.
+    # Among the configured patterns those are: "nyh", "ara", "med", "nwe".
     short_pattern_cases = [
         ("Brent NYH", "NYH"),
         ("NWE jet", "NWE"),
         ("ARA gasoil", "ARA"),
         ("Med fuel oil", "Med"),
+        # Word-boundary protection: "ara" must NOT match inside "Saharan"
+        ("Saharan crude", None),
     ]
     for text, expected in short_pattern_cases:
         assert normalize_region(text) == expected, (
             f"normalize_region({text!r}) should match {expected!r}"
         )
-        assert infer_region(text) is None, (
-            f"curvemetadata.infer_region({text!r}) is expected to return "
-            f"None (broken). Got {infer_region(text)!r}. If the bug is "
-            f"fixed, delete this test."
+        assert infer_region(text) == expected, (
+            f"curvemetadata.infer_region({text!r}) should match {expected!r} "
+            f"(got {infer_region(text)!r}). If you see None for one of the "
+            f"short patterns, the curvemetadata `\\b` regex bug has regressed."
         )
 
 
 def test_facade_reexports_visible_at_top_level():
-    # Smoke check: the eager facade exposes key symbols at top level.
+    # Smoke check: the lazy facade exposes key symbols via dir().
     import commodutil
 
     names = set(dir(commodutil))
@@ -150,3 +154,53 @@ def test_facade_unknown_attribute_raises():
 
     with pytest.raises(AttributeError):
         _ = commodutil.this_symbol_does_not_exist
+
+
+def test_facade_is_lazy_bare_import_does_not_load_convfactors():
+    """Regression guard for the PEP 562 lazy facade. `import commodutil`
+    must NOT eagerly load convfactors (pint registry + Commodity
+    dataclass init). Reverting the facade to eager would trip this and
+    the cost evidence is documented in the commit message that
+    introduced the lazy pattern (~3.3s -> ~2ms speedup)."""
+    import importlib
+    import sys
+
+    # Force a clean import to measure the bare cost.
+    for mod in [
+        "commodutil",
+        "commodutil.convfactors",
+        "commodutil.dates",
+        "commodutil.forwards",
+        "commodutil.pandasutil",
+        "commodutil.transforms",
+    ]:
+        sys.modules.pop(mod, None)
+
+    importlib.import_module("commodutil")
+    assert "commodutil.convfactors" not in sys.modules, (
+        "Lazy facade is broken — `import commodutil` triggered convfactors "
+        "load. Restore the PEP 562 __getattr__ pattern in commodutil/__init__.py."
+    )
+
+
+def test_facade_lazy_load_resolves_and_caches():
+    """First access of a facade symbol loads the source submodule and
+    caches the resolved value back into globals."""
+    import importlib
+    import sys
+
+    for mod in [
+        "commodutil",
+        "commodutil.convfactors",
+    ]:
+        sys.modules.pop(mod, None)
+
+    commodutil = importlib.import_module("commodutil")
+    assert "commodutil.convfactors" not in sys.modules
+
+    fn = commodutil.convert_price  # triggers lazy load
+    assert "commodutil.convfactors" in sys.modules
+    assert callable(fn)
+
+    # Second access hits the cache (still works, same object)
+    assert commodutil.convert_price is fn

commodutil-3.10.0/tests/test_standards_units.py

@@ -0,0 +1,86 @@
+"""Tests for commodutil.standards.units."""
+
+from commodutil.standards.units import default_unit_for_commodity
+
+
+def test_natgas_defaults_to_mmbtu():
+    assert default_unit_for_commodity("natgas") == "mmbtu"
+    assert default_unit_for_commodity("natural_gas") == "mmbtu"
+
+
+def test_refined_products_default_to_gal():
+    assert default_unit_for_commodity("gasoline") == "gal"
+    assert default_unit_for_commodity("diesel") == "gal"
+    assert default_unit_for_commodity("jet") == "gal"
+
+
+def test_crude_and_unknown_default_to_bbl():
+    assert default_unit_for_commodity("crude") == "bbl"
+    # Not in map — fallback to bbl
+    assert default_unit_for_commodity("butane") == "bbl"
+    assert default_unit_for_commodity("fuel_oil") == "bbl"
+
+
+def test_empty_and_none_default_to_bbl():
+    assert default_unit_for_commodity("") == "bbl"
+    assert default_unit_for_commodity(None) == "bbl"
+
+
+def test_case_insensitive():
+    assert default_unit_for_commodity("NATGAS") == "mmbtu"
+    assert default_unit_for_commodity("Gasoline") == "gal"
+
+
+# ---- UNIT_MAP tests ----
+
+
+def test_unit_map_canonical_values():
+    from commodutil.standards.units import UNIT_MAP
+
+    assert UNIT_MAP["barrel"] == "bbl"
+    assert UNIT_MAP["barrels"] == "bbl"
+    assert UNIT_MAP["bbl"] == "bbl"
+    assert UNIT_MAP["bbls"] == "bbl"
+
+
+def test_unit_map_gallon_variants():
+    from commodutil.standards.units import UNIT_MAP
+
+    assert UNIT_MAP["gallon"] == "gal"
+    assert UNIT_MAP["gallons"] == "gal"
+    assert UNIT_MAP["gal"] == "gal"
+
+
+def test_unit_map_metric_ton_variants():
+    from commodutil.standards.units import UNIT_MAP
+
+    assert UNIT_MAP["metric ton"] == "mt"
+    assert UNIT_MAP["metric tons"] == "mt"
+    assert UNIT_MAP["metric tonne"] == "mt"
+    assert UNIT_MAP["metric tonnes"] == "mt"
+    assert UNIT_MAP["tonne"] == "mt"
+    assert UNIT_MAP["tonnes"] == "mt"
+
+
+def test_unit_map_canonical_set_only_three():
+    """UNIT_MAP normalises to exactly the canonical units bbl / gal / mt."""
+    from commodutil.standards.units import UNIT_MAP
+
+    assert set(UNIT_MAP.values()) == {"bbl", "gal", "mt"}
+
+
+def test_unit_map_parity_with_curvemetadata():
+    """Regression guard: UNIT_MAP must match curvemetadata's previous local
+    copy byte-for-byte until curvemetadata's re-export PR lands. Skipped if
+    curvemetadata is unavailable."""
+    try:
+        from curvemetadata.common_maps import UNIT_MAP as cm_UNIT_MAP
+    except ImportError:
+        import pytest
+
+        pytest.skip("curvemetadata not available in this environment")
+
+    from commodutil.standards.units import UNIT_MAP
+
+    # Parity: every key/value in the curvemetadata copy is in commodutil's
+    assert cm_UNIT_MAP == UNIT_MAP

commodutil-3.9.0/commodutil/__init__.py

@@ -1,84 +0,0 @@
-"""commodutil: Commodity market standards backbone.
-
-Public API for unit conversions, forward curve transforms, date utilities,
-and pandas helpers. Re-exports the most-used symbols from sub-modules so
-callers can write `from commodutil import convert_price` instead of
-`from commodutil.convfactors import convert_price`.
-"""
-
-from commodutil.convfactors import (
-    ALIASES,
-    COMMODITIES,
-    Commodity,
-    FRACTIONAL_TO_MAJOR,
-    VALID_CURRENCY_TOKENS,
-    convert,
-    convert_price,
-    convfactor,
-    fractional_to_major,
-    is_fractional_currency,
-    list_commodities,
-    list_units,
-    split_currency_unit,
-)
-from commodutil.dates import (
-    curmon,
-    curmonyear,
-    curmonyear_str,
-    curyear,
-    find_year,
-    last_day_of_prev_month,
-    nextyear,
-    prevmon,
-    prevmon_str,
-    prevyear,
-    start_day_of_prev_month,
-)
-from commodutil.forwards import (
-    all_spread_combinations,
-    time_spreads,
-)
-from commodutil.pandasutil import (
-    fillna_downbet,
-    mergets,
-)
-from commodutil.transforms import (
-    seasonalize,
-)
-
-__all__ = [
-    # convfactors
-    "ALIASES",
-    "COMMODITIES",
-    "Commodity",
-    "FRACTIONAL_TO_MAJOR",
-    "VALID_CURRENCY_TOKENS",
-    "convert",
-    "convert_price",
-    "convfactor",
-    "fractional_to_major",
-    "is_fractional_currency",
-    "list_commodities",
-    "list_units",
-    "split_currency_unit",
-    # dates
-    "curmon",
-    "curmonyear",
-    "curmonyear_str",
-    "curyear",
-    "find_year",
-    "last_day_of_prev_month",
-    "nextyear",
-    "prevmon",
-    "prevmon_str",
-    "prevyear",
-    "start_day_of_prev_month",
-    # forwards
-    "all_spread_combinations",
-    "time_spreads",
-    # pandasutil
-    "fillna_downbet",
-    "mergets",
-    # transforms
-    "seasonalize",
-]

commodutil-3.9.0/commodutil/standards/units.py

@@ -1,30 +0,0 @@
-"""commodutil.standards.units: default-unit helpers per commodity.
-
-Lifted from pyoilprice/conversion.py's inline fallback. Pure vocab — no
-pint, no pandas.
-"""
-
-from __future__ import annotations
-
-
-_DEFAULT_UNIT = {
-    "natgas": "mmbtu",
-    "natural_gas": "mmbtu",
-    "gasoline": "gal",
-    "diesel": "gal",
-    "jet": "gal",
-}
-
-
-def default_unit_for_commodity(commodity: str) -> str:
-    """Return the canonical quoted unit for a commodity (volume basis).
-
-    Falls back to 'bbl' for any commodity not in the explicit map (covers
-    crude / fuel oil / naphtha / VGO / NGL species etc.).
-    """
-    if not commodity:
-        return "bbl"
-    return _DEFAULT_UNIT.get(str(commodity).lower(), "bbl")
-
-
-__all__ = ["default_unit_for_commodity"]

commodutil-3.9.0/tests/test_standards_units.py

@@ -1,31 +0,0 @@
-"""Tests for commodutil.standards.units."""
-
-from commodutil.standards.units import default_unit_for_commodity
-
-
-def test_natgas_defaults_to_mmbtu():
-    assert default_unit_for_commodity("natgas") == "mmbtu"
-    assert default_unit_for_commodity("natural_gas") == "mmbtu"
-
-
-def test_refined_products_default_to_gal():
-    assert default_unit_for_commodity("gasoline") == "gal"
-    assert default_unit_for_commodity("diesel") == "gal"
-    assert default_unit_for_commodity("jet") == "gal"
-
-
-def test_crude_and_unknown_default_to_bbl():
-    assert default_unit_for_commodity("crude") == "bbl"
-    # Not in map — fallback to bbl
-    assert default_unit_for_commodity("butane") == "bbl"
-    assert default_unit_for_commodity("fuel_oil") == "bbl"
-
-
-def test_empty_and_none_default_to_bbl():
-    assert default_unit_for_commodity("") == "bbl"
-    assert default_unit_for_commodity(None) == "bbl"
-
-
-def test_case_insensitive():
-    assert default_unit_for_commodity("NATGAS") == "mmbtu"
-    assert default_unit_for_commodity("Gasoline") == "gal"