commodutil 4.7.0__tar.gz → 5.4.0__tar.gz

commodutil-5.4.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 5.4.0 - 2026-07-12
+
+- Added `normalize_price_unit_strict` and `is_canonical_price_unit` to `commodutil.standards.units` (and the `commodutil` / `commodutil.standards` facades): the STRICT counterpart to the lenient `canonical_price_unit_token`. Where the lenient token preserves unrecognised currency/unit fragments so it can label any quote string, the strict variant returns a canonical `CCY/unit` token only when both legs resolve (recognised currency over a `canonical_quantity_unit` denominator) and `None` otherwise — for validating a curated price-unit qualifier that must round-trip through conversion (e.g. `usd_ton`/`USD/ton` refused, `USD/MT` -> `USD/mt`).
+
+## 5.0.1 - 2026-07-03
+
+- Breaking: removed `default_unit_for_commodity` and `_DEFAULT_UNIT` from `commodutil.standards.units`; these fabricated per-commodity quote units, and the gold instrument registry answers this per-instrument.
+- Breaking: removed the `commodutil.standards.price_units` module. Price-unit resolution (`resolve_price_unit`, `resolve_price_unit_from_attrs`) moved into `commodutil.standards.price_unit` alongside the `PriceUnit` value type. Migrate imports to `commodutil.standards.price_unit`.
+- First release of the 5.x line; the 5.0.0 version number is unusable on the feed.
+
+## 4.10.0 - 2026-07-03
+
+- Added exchange unit spellings for `MTONS`, `CBM`, `THM`, and `KL` to the unit registry, with `KL`/kilolitre spellings resolving to the canonical `m^3` unit.
+- Moved commodity alias ownership to `commodutil.standards.commodities.COMMODITY_ALIASES`; `CommodityConverter` now consumes a defensive copy from that source.
+- Breaking: removed the `commodutil.convfactors.ALIASES` re-export. Migrate callers to `from commodutil.standards.commodities import COMMODITY_ALIASES`.
+
+## 4.8.0 - 2026-07-03
+
+- Split price, currency, and FX conversion helpers into `commodutil.priceconv`, while keeping lazy compatibility exports from `commodutil.convfactors` for the price-conversion API.
+- Consolidated petrochemical taxonomy keywords into `commodutil.standards.commodities`.
+- Added `infer_ngl_species` for discrete NGL species inference from free text.
+
+## 4.7.0 - 2026-07-03
+
+- Fixed ethanol density to `0.7937 kg/L`, preserving the EIA gross per-volume energy content while correcting mass-based conversion factors.
+- Promoted `kg` and bare cubic-metre spellings (`m3`, `m^3`, `m**3`) into the `UNIT_MAP` tier so vendor-spec parsers can resolve them directly.
+
+## 4.6.0 - 2026-07-02
+
+- Replaced hand-rolled scalar rate-period conversion with `PriceUnit` parsing and Pint-derived period ratios, while preserving calendar-aware month/day handling for series.
+- Added `align_fx`, `ConversionResult`, and `convert_price_result` for explicit price-conversion results, currency-leg fallback, and keep-raw error handling.
+
+## 4.5.0 - 2026-07-02
+
+- Added the `PriceUnit` value type for structured price-unit parsing across currency, quantity-unit, and rate-period legs.
+- Added `commodutil.standards.unit_registry` as the single source of truth for unit vocabulary, public unit maps, and Pint definitions.
+- Added ICE unit spellings for `MMBtu`, `GJ`, `MWh`, `m^3`, `MW`, `RIN`, `FEU`, and `day`, covering the registry gap identified in ICE contract metadata.
+
+## 4.4.0 - 2026-07-02
+
+- Standardized covered liquid and biofuel energy-content factors on the EIA gross/HHV basis, documenting explicit exceptions and basis assumptions.
+- Added API2/coal support with mass-basis energy content for density-less solid-fuel conversions and Coal taxonomy inference.
+- Added the golden-factor regression fixture and validation tests for quantity, rate, and price conversions.

{commodutil-4.7.0 → commodutil-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.7.0
+Version: 5.4.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-4.7.0 → commodutil-5.4.0}/commodutil/__init__.py

@@ -22,7 +22,6 @@ from __future__ import annotations
 # resolve via __getattr__ below.
 _LAZY_EXPORTS = {
     # convfactors (heaviest -- pint registry + Commodity dataclass init)
-    "ALIASES": "commodutil.convfactors",
     "COMMODITIES": "commodutil.convfactors",
     "Commodity": "commodutil.convfactors",
     "convert": "commodutil.convfactors",
@@ -41,6 +40,8 @@ _LAZY_EXPORTS = {
     "canonical_price_unit_token": "commodutil.standards.units",
     "canonical_quantity_unit": "commodutil.standards.units",
     "canonical_unit_token": "commodutil.standards.units",
+    "is_canonical_price_unit": "commodutil.standards.units",
+    "normalize_price_unit_strict": "commodutil.standards.units",
     "quantity_unit_from_price_unit": "commodutil.standards.units",
     # dates
     "curmon": "commodutil.dates",

{commodutil-4.7.0 → commodutil-5.4.0}/commodutil/convfactors.py

@@ -1,6 +1,8 @@
 """
 Modern implementation of commodity unit conversions using Pint.
 Clean-slate design with no backward-compatibility constraints.
+
+Module map: quantity/pint conversion lives here; price/currency/FX lives in ``commodutil.priceconv``; vocabulary lives in ``commodutil.standards.unit_registry``; ``PriceUnit`` grammar and resolve precedence live in ``commodutil.standards.price_unit``.
 """
 
 import logging
@@ -11,7 +13,7 @@ from dataclasses import dataclass
 import pandas as pd
 from functools import lru_cache
 
-from commodutil.standards import currency as _currency
+from commodutil.standards.commodities import COMMODITY_ALIASES as _COMMODITY_ALIASES
 from commodutil.standards.price_unit import PriceUnit
 from commodutil.standards.unit_registry import PINT_DEFINITIONS as _PINT_DEFINITIONS
 from commodutil.standards.units import to_pint_token as _to_pint_token
@@ -204,48 +206,6 @@ COMMODITIES = {
     # GCV = 29.29 GJ/t) which understated coal $/MMBtu by ~11%.
 }
 
-# Aliases for compatibility
-ALIASES = {
-    # Common synonyms and marketing terms
-    "ulsd": "diesel",
-    "gasoil": "diesel",
-    "gas_oil": "diesel",
-    "gas oil": "diesel",
-    "go": "diesel",
-    "kerosene": "jet",
-    # Motor gasoline
-    "gas": "gasoline",
-    "mogas": "gasoline",
-    # Fuel oil
-    "fueloil": "fuel_oil",
-    "fuel oil": "fuel_oil",
-    "fo": "fuel_oil",
-    # Crude
-    "crude oil": "crude",
-    "crudeoil": "crude",
-    # LPG and nat gas
-    # Note: 'propane'/'butane'/'isobutane'/'natural_gasoline' are now first-class
-    # entries in COMMODITIES (added 2026-05 for $/gal<->$/MMBtu work on the
-    # MB OPIS NGL futures). The legacy 'propane -> lpg' alias is gone; existing
-    # callers using commodity='lpg' for a generic LPG blend still work via the
-    # 'lpg' entry. NGL-species aliases below cover common spellings.
-    "n_butane": "butane",
-    "n-butane": "butane",
-    "normal_butane": "butane",
-    "normal butane": "butane",
-    "iso_butane": "isobutane",
-    "iso-butane": "isobutane",
-    "i_butane": "isobutane",
-    "i-butane": "isobutane",
-    "natgaso": "natural_gasoline",
-    "nat_gasoline": "natural_gasoline",
-    "pentanes_plus": "natural_gasoline",
-    "lng": "natgas",  # LNG (liquefied natural gas)
-    "ng": "natural_gas",  # pipeline natural gas (gaseous)
-    "naturalgas": "natural_gas",
-    "nat_gas": "natural_gas",
-}
-
 
 class CommodityConverter:
     """Clean, modern interface for commodity unit conversions"""
@@ -253,7 +213,12 @@ class CommodityConverter:
     def __init__(self):
         self.ureg = ureg
         self.commodities = COMMODITIES
-        self.aliases = ALIASES
+        # Alias (spelling/synonym) -> canonical COMMODITIES key. Sole owner is
+        # commodutil.standards.commodities.COMMODITY_ALIASES (grouped by target;
+        # edit there). Defensive copy so converter-local mutation can't touch
+        # the owner. The old convfactors.ALIASES re-export was removed with the
+        # B1 consolidation — import COMMODITY_ALIASES from standards instead.
+        self.aliases = dict(_COMMODITY_ALIASES)
 
     @lru_cache(maxsize=128)
     def get_commodity(self, name: str) -> Commodity:
@@ -576,421 +541,38 @@ def convfactor(
     return converter.convert(1.0, from_unit, to_unit, commodity)
 
 
-# ---- Currency-aware price conversion helpers ----
-#
-# 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.
-
-
-def align_fx(
-    fx: pd.Series,
-    index: pd.Index,
-    policy: str = "strict",
-    max_staleness: pd.Timedelta = pd.Timedelta(days=7),
-) -> pd.Series:
-    """Align an FX Series onto ``index`` for a price conversion.
-
-    Extracted verbatim from ``convert_price`` (Phase 3.4) so new code can compose
-    FX alignment explicitly; ``convert_price`` delegates here, so behaviour and
-    error/warning text are unchanged.
-
-    - ``policy='strict'`` (default): forward-fill FX onto ``index`` bounded by
-      ``max_staleness``; any target date left uncovered (pre-FX-start, or stale
-      past the limit) raises ``ValueError`` rather than silently back-filling or
-      extrapolating.
-    - ``policy='ffill'``: permissive — union the indices, ffill across the union,
-      reindex back, and fill any residual NaN with the most-recent non-null FX.
-      Emits a logging warning (future-leakage risk in backtests). Raises only if
-      the FX series is entirely NaN.
-    """
-    target_idx = index
-
-    if policy == "strict":
-        # Bounded ffill: only forward-fill within `max_staleness`. Anything
-        # uncovered (e.g. value-dates before fx.index.min() or stale past
-        # the limit) stays NaN and triggers a loud raise — no silent
-        # back-fill, no silent stale extrapolation.
-        union_idx = fx.index.union(target_idx)
-        fx_union = fx.reindex(union_idx).sort_index().ffill()
-        # Track how stale each ffilled value is and zero-out anything older
-        # than max_staleness.
-        valid_mask = ~fx.reindex(union_idx).isna()
-        last_valid_pos = pd.Series(union_idx, index=union_idx).where(valid_mask).ffill()
-        staleness = pd.Series(union_idx, index=union_idx) - last_valid_pos
-        fx_union = fx_union.where(staleness <= max_staleness)
-        fx_aligned = fx_union.reindex(target_idx)
-        if fx_aligned.isna().any():
-            missing = target_idx[fx_aligned.isna()]
-            first_missing = missing[0]
-            first_missing_str = (
-                first_missing.date()
-                if hasattr(first_missing, "date")
-                else first_missing
-            )
-            raise ValueError(
-                f"FX missing or stale (>{max_staleness}) for "
-                f"{len(missing)} target date(s) (first: {first_missing_str}). "
-                f"Pass ffill_policy='ffill' to fill with the last non-null "
-                f"FX (BACKTEST FUTURE LEAKAGE RISK)."
-            )
-    elif policy == "ffill":
-        logger.warning(
-            "convert_price: ffill_policy='ffill' — pre-FX-start dates will "
-            "be back-filled with the latest FX. Future-leakage risk in "
-            "backtests; prefer 'strict' for historical research."
-        )
-        if not target_idx.isin(fx.index).all():
-            union_idx = fx.index.union(target_idx)
-            fx_aligned = fx.reindex(union_idx).ffill().reindex(target_idx)
-        else:
-            fx_aligned = fx.reindex(target_idx).ffill()
-        if fx_aligned.isna().any():
-            fx_nonnull = fx.dropna()
-            if fx_nonnull.size == 0:
-                raise ValueError(
-                    "FX series is entirely NaN; refusing the silent "
-                    "multiply-by-1.0 fallback."
-                )
-            fx_aligned = fx_aligned.fillna(fx_nonnull.iloc[-1])
-    else:
-        raise ValueError(
-            f"Unknown ffill_policy: {policy!r} (expected 'strict' or 'ffill')"
-        )
-
-    return fx_aligned
-
-
-def convert_price(
-    value: Union[float, pd.Series],
-    from_unit: Union[str, PriceUnit],
-    to_unit: Union[str, PriceUnit],
-    commodity: Optional[str] = None,
-    fx: Union[float, pd.Series, None] = None,
-    ffill_policy: str = "strict",
-    max_staleness: pd.Timedelta = pd.Timedelta(days=7),
-) -> Union[float, pd.Series]:
-    """
-    Convert price values ($/unit) between units, optionally bearing an FX rate.
-
-    Price conversion is the inverse of quantity conversion:
-        price_to = price_from / convfactor(from_unit, to_unit, commodity)
-
-    If `from_unit` and `to_unit` differ in currency (e.g. EUR/MWh -> USD/MMBtu),
-    `fx` must be supplied (scalar or pandas.Series indexed by date), quoted as
-    target/source — i.e. USD-per-foreign-currency. Fractional-currency
-    prefixes ('GBp', 'USc', ...) are auto-detected and divided by 100.
-
-    If `fx` is a Series and `value` is a Series, alignment policy is controlled
-    by `ffill_policy` and `max_staleness`:
-
-    - `ffill_policy='strict'` (default): FX is forward-filled onto value.index
-      with a bounded ffill of `max_staleness`. If any target dates remain
-      uncovered, a `ValueError` is raised — refusing to silently back-fill
-      pre-FX-start dates (which would be future leakage in backtests) or
-      to extend stale FX values indefinitely.
-    - `ffill_policy='ffill'`: legacy permissive behaviour — union the two
-      indices, ffill across the union, then reindex back; any remaining
-      NaNs are filled with the most-recent non-null FX. Emits a logging
-      warning because this is unsafe for backtests.
+def list_commodities():
+    """List all available commodities"""
+    return converter.available_commodities
 
-    There is no all-NaN `1.0` fallback. If FX is unusable, the function raises.
 
-    `from_unit` / `to_unit` are EITHER bare units ('mt', 'bbl', 'gal', 'MMBtu',
-    'MWh', 'therm') OR currency-qualified ('USD/bbl', 'EUR/MWh', 'GBp/therm').
-    Currency-qualified targets are currently restricted to USD (anything else
-    raises ValueError — extend in future if non-USD targets are needed).
+def list_units():
+    """List common units"""
+    # Return normalized forms to avoid encoding issues
+    return [_to_pint_token(u) for u in converter.available_units]
 
-    Examples:
-        # Gasoline: $/mt -> $/bbl (divide by ~8.33)
-        convert_price(100, 'mt', 'bbl', commodity='gasoline')  # ~12.0
 
-        # US gallon to barrel: $/gal -> $/bbl (multiply by 42)
-        convert_price(2.5, 'gal', 'bbl')  # ~105.0
+_PRICECONV_EXPORTS = {
+    "align_fx",
+    "convert_price",
+    "convert_currency_leg",
+    "ConversionResult",
+    "convert_price_result",
+}
 
-        # TTF EUR/MWh -> $/MMBtu (EURUSD = 1.07)
-        convert_price(35.0, 'EUR/MWh', 'USD/MMBtu', fx=1.07)  # ~10.98
 
-        # NBP GBp/therm -> $/MMBtu (GBPUSD = 1.25); GBp auto-detected & /100
-        convert_price(80.0, 'GBp/therm', 'USD/MMBtu', fx=1.25)  # ~10.00
+def __getattr__(name: str):
+    if name in _PRICECONV_EXPORTS:
+        from importlib import import_module
 
-        # Time-varying FX with a pandas Series
-        p = pd.Series([35.0, 36.5, 34.2], index=pd.date_range('2026', periods=3))
-        fx_series = pd.Series([1.07, 1.08, 1.06], index=p.index)
-        convert_price(p, 'EUR/MWh', 'USD/MMBtu', fx=fx_series)
-    """
-    # Parse each side once at the boundary into a PriceUnit and read its legs,
-    # instead of re-splitting raw strings. PriceUnit.parse is built on
-    # split_currency_unit, so (currency, quantity_leg) is byte-identical to the
-    # previous split_currency_unit(...) result — behaviour and error strings are
-    # unchanged. from_unit/to_unit are re-bound to the canonical string form for
-    # use in the error messages / examples below.
-    from_pu = (
-        from_unit if isinstance(from_unit, PriceUnit) else PriceUnit.parse(from_unit)
-    )
-    to_pu = to_unit if isinstance(to_unit, PriceUnit) else PriceUnit.parse(to_unit)
-    from_unit = str(from_pu)
-    to_unit = str(to_pu)
-    from_ccy, from_bare_unit = (from_pu.currency or ""), from_pu.quantity_leg()
-    to_ccy, to_bare_unit = (to_pu.currency or ""), to_pu.quantity_leg()
-
-    # 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 = _currency.FRACTIONAL_TO_MAJOR.get(
-        from_ccy, from_ccy.upper() if from_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"
-    if to_major == "$":
-        to_major = "USD"
-
-    same_base_fractional = bool(from_ccy and to_ccy and from_major == to_major)
-
-    # Validate target currency — explicit USD only for now (only enforced when
-    # the target is currency-qualified at all AND we're not in a same-base
-    # fractional case like GBp/therm -> GBP/therm, which is a pure scale).
-    if to_ccy and to_major != "USD" and not same_base_fractional:
-        raise ValueError(
-            f"convert_price currently only supports USD/* as target; got '{to_unit}'"
-        )
-
-    # Unit-leg conversion (no FX yet — uses commodity factors).
-    # convfactor returns a nonzero float or raises, so no None/zero guard is
-    # needed here.
-    factor = convfactor(from_bare_unit, to_bare_unit, commodity)
-    unit_converted = value / factor
-
-    # Same-base fractional case: USc -> USD, GBp -> GBP, EUc -> EUR, JPy -> JPY.
-    # This is a pure /100 scale (or *100 in the reverse direction) — no FX
-    # needed even though the literal currency tokens differ. Handle BEFORE the
-    # `fx is None` raise below.
-    if same_base_fractional:
-        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)
-
-    # If no source currency or it's already USD, no FX leg needed
-    if not from_ccy or from_major == "USD":
-        return unit_converted
-
-    # Apply FX leg
-    if fx is None:
-        raise ValueError(
-            f"FX rate required to convert {from_unit} -> {to_unit} "
-            f"(source currency '{from_ccy}' is non-USD)"
-        )
-
-    fractional_divisor = _currency.FRACTIONAL_CURRENCY_DIVISORS.get(from_ccy, 1.0)
-
-    if isinstance(unit_converted, pd.Series) and isinstance(fx, pd.Series):
-        fx_aligned = align_fx(
-            fx, unit_converted.index, policy=ffill_policy, max_staleness=max_staleness
-        )
-        return unit_converted * fx_aligned / fractional_divisor
-
-    return unit_converted * fx / fractional_divisor
-
-
-def convert_currency_leg(
-    value: Union[float, pd.Series],
-    from_unit: Union[str, PriceUnit],
-    to_unit: Union[str, PriceUnit],
-    fx: Union[float, pd.Series, None] = None,
-) -> Union[float, pd.Series]:
-    """Convert ONLY the currency leg of a price whose quantity denominator is
-    unchanged.
-
-    This is the separable-currency-leg helper from the conversion architecture
-    plan (Phase 3.1). Unlike :func:`convert_price`, it performs NO physical-unit
-    conversion and never calls :func:`convfactor`, so it works when the quantity
-    denominator is non-physical or unknown to pint — e.g. ``'USc/RIN' ->
-    'USD/RIN'`` (a pure ``/100`` scale). ``convert_price`` cannot do that today
-    because it tries to compute ``convfactor('RIN', 'RIN')`` and raises on the
-    unknown unit.
-
-    It reimplements, as a first-class API, the broad-except ``/100.0`` currency
-    fallback shim in ``oilrisk``'s ``artis.py`` (lines ~75-98): scale a
-    fractional-currency quote (USc, GBp, ...) to its major unit without needing a
-    commodity or a physical factor.
-
-    Rules:
-      * The two quantity denominators must be **string-equal** after parsing
-        (``from`` and ``to`` refer to the same thing priced per identical unit);
-        otherwise ``ValueError``. No physical-unit validation is performed.
-      * Same-base fractional (``USc``->``USD``, ``GBp``->``GBP``): pure divisor
-        scale, no ``fx`` needed.
-      * No source currency, or source already the USD major: no-op (returns
-        ``value`` unchanged).
-      * Cross major-currency (e.g. ``EUR``->``USD``): ``fx`` is required (quoted
-        target-per-source) or ``ValueError`` is raised. ``fx`` is applied
-        element-wise; index-aligned FX Series are the caller's responsibility
-        (use :func:`convert_price` for the strict/ffill staleness machinery).
-      * Target currency is restricted to USD (matching ``convert_price``),
-        except pure same-base fractional scaling like ``GBp``->``GBP``.
-
-    Examples:
-        convert_currency_leg(250.0, 'USc/RIN', 'USD/RIN')   # -> 2.5  (/100)
-        convert_currency_leg(50.0, 'GBp/therm', 'GBP/therm')  # -> 0.5
-        convert_currency_leg(10.0, 'EUR/RIN', 'USD/RIN', fx=1.07)  # -> 10.7
-    """
-    from_pu = (
-        from_unit if isinstance(from_unit, PriceUnit) else PriceUnit.parse(from_unit)
-    )
-    to_pu = to_unit if isinstance(to_unit, PriceUnit) else PriceUnit.parse(to_unit)
-
-    # Quantity denominators must match exactly — string equality only, so a
-    # non-physical denominator like 'RIN' is fine (no pint lookup).
-    if from_pu.quantity_leg() != to_pu.quantity_leg():
-        raise ValueError(
-            f"convert_currency_leg requires identical quantity denominators; "
-            f"got '{from_pu.quantity_leg()}' vs '{to_pu.quantity_leg()}'"
-        )
-
-    from_ccy = from_pu.currency or ""
-    to_ccy = to_pu.currency or ""
-    from_major = from_pu.major_currency or ""
-    to_major = to_pu.major_currency or ""
-
-    same_base_fractional = bool(from_ccy and to_ccy and from_major == to_major)
-
-    # USD-only currency target, except pure same-base fractional scaling.
-    if to_ccy and to_major != "USD" and not same_base_fractional:
-        raise ValueError(
-            f"convert_currency_leg currently only supports USD/* as target; "
-            f"got '{to_pu}'"
-        )
-
-    # Same-base fractional (USc->USD, GBp->GBP, ...): pure divisor scale.
-    if same_base_fractional:
-        return value * (to_pu.fractional_divisor / from_pu.fractional_divisor)
-
-    # No source currency, or already USD major: currency leg is a no-op.
-    if not from_ccy or from_major == "USD":
+        value = getattr(import_module("commodutil.priceconv"), name)
+        globals()[name] = value
         return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-    # Cross major-currency: an FX leg is required.
-    if fx is None:
-        raise ValueError(
-            f"FX rate required to convert {from_pu} -> {to_pu} "
-            f"(source currency '{from_ccy}' is non-USD)"
-        )
-    return value * fx / from_pu.fractional_divisor
-
-
-@dataclass(frozen=True)
-class ConversionResult:
-    """Result of :func:`convert_price_result`.
-
-    - ``value``: the converted price (float or pandas Series).
-    - ``applied``: True when a non-identity conversion route ran (from/to differ);
-      False for an identity ('unchanged') or a kept-raw error.
-    - ``note``: which route produced ``value`` — e.g.
-      ``'convert_price:USD/mt->USD/bbl[diesel]'``, ``'currency_leg:USc/RIN->USD/RIN'``,
-      ``'unchanged'``, or ``'kept-raw:<error>'``.
-    """
-
-    value: Union[float, pd.Series]
-    applied: bool
-    note: str
-
-
-def convert_price_result(
-    value: Union[float, pd.Series],
-    from_unit: Union[str, PriceUnit],
-    to_unit: Union[str, PriceUnit],
-    commodity: Optional[str] = None,
-    fx: Union[float, pd.Series, None] = None,
-    ffill_policy: str = "strict",
-    max_staleness: pd.Timedelta = pd.Timedelta(days=7),
-    on_error: str = "raise",
-) -> ConversionResult:
-    """Result-bearing wrapper over :func:`convert_price`: returns a
-    :class:`ConversionResult` (value, applied, note) instead of a bare value.
-
-    Both oilrisk price loaders (``artis.py`` and
-    ``load_marketplace_price_snapshots.py``) independently invented exactly this
-    ``(value, changed?, source_note)`` shape around convert_price; this is the
-    shared primitive they unify onto in Phase 4.2.
-
-    Same parameters as :func:`convert_price`, plus:
-      * ``on_error='raise'`` (default): a conversion failure propagates, so plain
-        use stays strict.
-      * ``on_error='keep'``: on failure (and when no currency-leg fallback
-        applies) return the ORIGINAL ``value`` with ``applied=False`` and a
-        ``'kept-raw:...'`` note — the keep-raw semantic oilrisk wants for rows it
-        can't convert but must not drop.
-
-    Fallback: if the full conversion fails but both units are currency-qualified
-    with equal quantity denominators, the currency leg alone is applied via
-    :func:`convert_currency_leg` (e.g. ``'USc/RIN'->'USD/RIN'``), with a
-    ``'currency_leg:...'`` note — mirroring the fallback oilrisk's artis.py does
-    at its call site so Phase 4.2 can delete that logic there.
-    """
-    if on_error not in ("raise", "keep"):
-        raise ValueError(f"on_error must be 'raise' or 'keep', got {on_error!r}")
-
-    from_pu = (
-        from_unit if isinstance(from_unit, PriceUnit) else PriceUnit.parse(from_unit)
-    )
-    to_pu = to_unit if isinstance(to_unit, PriceUnit) else PriceUnit.parse(to_unit)
-    label = f"{from_pu}->{to_pu}"
-    if commodity:
-        label += f"[{commodity}]"
-
-    # Identity: same currency + unit + period -> nothing to do.
-    if from_pu == to_pu:
-        return ConversionResult(value=value, applied=False, note="unchanged")
 
-    try:
-        out = convert_price(
-            value,
-            from_pu,
-            to_pu,
-            commodity,
-            fx=fx,
-            ffill_policy=ffill_policy,
-            max_staleness=max_staleness,
-        )
-        return ConversionResult(value=out, applied=True, note=f"convert_price:{label}")
-    except Exception as exc:
-        # Currency-leg fallback: the full conversion failed, but if both sides
-        # are currency-qualified with equal denominators the currency scale is
-        # still well-defined (e.g. convert_price can't do convfactor('RIN',
-        # 'RIN'), but 'USc/RIN'->'USD/RIN' is a clean /100).
-        if (
-            from_pu.is_currency_qualified
-            and to_pu.is_currency_qualified
-            and from_pu.quantity_leg() == to_pu.quantity_leg()
-        ):
-            try:
-                out = convert_currency_leg(value, from_pu, to_pu, fx=fx)
-                return ConversionResult(
-                    value=out, applied=True, note=f"currency_leg:{label}"
-                )
-            except Exception:
-                pass  # fall through to on_error handling
-        if on_error == "keep":
-            return ConversionResult(value=value, applied=False, note=f"kept-raw:{exc}")
-        raise
-
-
-def list_commodities():
-    """List all available commodities"""
-    return converter.available_commodities
-
-
-def list_units():
-    """List common units"""
-    # Return normalized forms to avoid encoding issues
-    return [_to_pint_token(u) for u in converter.available_units]
+def __dir__():
+    return sorted(set(globals()) | _PRICECONV_EXPORTS)
 
 
 # Example usage