commodutil 4.4.0__tar.gz → 4.6.0__tar.gz

{commodutil-4.4.0 → commodutil-4.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.4.0
+Version: 4.6.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.4.0 → commodutil-4.6.0}/commodutil/convfactors.py

@@ -12,6 +12,8 @@ import pandas as pd
 from functools import lru_cache
 
 from commodutil.standards import currency as _currency
+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
 
 logger = logging.getLogger(__name__)
@@ -31,48 +33,19 @@ ureg = pint.UnitRegistry()
 
 # Define oil & gas specific units.
 #
-# Pint already ships a `barrel` unit but its default (US dry barrel,
-# ~119.24 L) is NOT the oil/petroleum barrel. Rather than silently
-# clobbering pint's default (which would mean downstream callers using
-# `ureg.barrel` for non-oil contexts get the wrong answer), we register
-# a distinct `oil_barrel` (158.987294928 L = 42 US gallons) and route
-# the `bbl` alias to it. `ureg.barrel` retains pint's default meaning.
-ureg.define("oil_barrel = 158.987294928 liter = bbl")
-ureg.define("gallon = 3.785411784 liter = gal")
-ureg.define("metric_ton = 1000 kilogram = mt")
-ureg.define("kiloton = 1000 metric_ton = kt")
-ureg.define("cubic_kilometer = 1e9 meter**3 = km3")  # 1 km^3 = 1 billion m^3
-ureg.define("gigajoule = 1e9 joule = gj = GJ")
-ureg.define("petajoule = 1e15 joule = pj = PJ")
-ureg.define("billion_cubic_meter = 1e9 meter**3 = bcm = BCM")
-ureg.define("billion_cubic_foot = 1e9 foot**3 = bcf = BCF")
-ureg.define("tonne_of_oil_equivalent = 41.868e9 joule = toe = TOE")
-ureg.define("million_tonne_of_oil_equivalent = 1e6 tonne_of_oil_equivalent = Mtoe")
-ureg.define("barrel_of_oil_equivalent = 6.119e9 joule = boe = BOE")
-ureg.define("million_barrel_of_oil_equivalent = 1e6 barrel_of_oil_equivalent = Mboe")
-ureg.define("megatonne = 1e6 metric_ton = Mt")
-# Pint defines `Btu` (= 1055.056 J) and `therm` (= 1e5 Btu) but NOT `MMBtu`.
-# The natgas / NGL pages quote in $/MMBtu, so register it explicitly (and the
-# normalize_unit helper already maps 'MMBTU' -> 'MMBtu').
-ureg.define("million_british_thermal_unit = 1e6 Btu = MMBtu")
-
-# Case-insensitive aliases for the most-quoted energy / power units.
-# Pint is case-sensitive by default, so `ureg('mmbtu')` or `ureg('mw')` raise
-# UndefinedUnitError even though `MMBtu` / `MW` work. Callers (Power Query, ad-hoc
-# scripts, copy-pasted Platts symbols) very commonly use the lowercase / all-caps
-# / underscored forms, so register them explicitly here.
-#
-# Energy: MMBtu + therm + Btu spellings (MMBtu is defined above; therm + Btu are
-# in pint's defaults). `million_btu` is the long-form alias.
-ureg.define("@alias million_british_thermal_unit = mmbtu = MMBTU = million_btu")
-ureg.define("@alias therm = Therm = THERM")
-ureg.define("@alias british_thermal_unit = btu")
-# Power / energy: MW and MWh are SI-prefix forms of `watt` / `watt_hour`, so they
-# cannot be aliased via `@alias`. Register lowercase / all-caps spellings as
-# standalone units with the same magnitude.
-ureg.define("mw = 1e6 watt")
-ureg.define("mwh = 1e6 watt * hour")
-ureg.define("MWH = 1e6 watt * hour")
+# The exact pint definitions (and their required ordering) live as the
+# `pint_specs` of each row in commodutil.standards.unit_registry; they are
+# applied here in registry order. This includes the load-bearing re-routes and
+# case spellings that keep this registry correct:
+#   * `oil_barrel` (158.987294928 L = 42 US gal) with `bbl` routed to it —
+#     pint's default `barrel` is the US dry barrel (~119.24 L), left untouched.
+#   * `metric_ton = mt` — pint's `mt` would otherwise be milli-tonne.
+#   * MMBtu, plus case aliases (mmbtu/MMBTU, therm/THERM, btu) and lowercase /
+#     all-caps power spellings (mw, mwh, MWH) — the registry stays CASE-SENSITIVE
+#     (kt/kilotesla etc. collide non-deterministically under case-folding).
+# To add or change a unit definition, edit its UnitRow in the registry.
+for _definition in _PINT_DEFINITIONS:
+    ureg.define(_definition)
 
 
 @dataclass
@@ -294,8 +267,8 @@ class CommodityConverter:
     def convert(
         self,
         value: Union[float, pd.Series],
-        from_unit: str,
-        to_unit: str,
+        from_unit: Union[str, PriceUnit],
+        to_unit: Union[str, PriceUnit],
         commodity: Optional[str] = None,
     ) -> Union[float, pd.Series]:
         """
@@ -314,34 +287,42 @@ class CommodityConverter:
             # With pandas Series and daily rates
             convert(series, 'kt/month', 'bbl/day', commodity='gasoline')
         """
-        # Normalize and parse units to handle daily/monthly rates
+        # Accept PriceUnit | str at the boundary: a PriceUnit collapses to its
+        # canonical string form, which the existing rate/pint logic then handles
+        # unchanged (convert/convfactor operate on bare & rate units, never on
+        # currency-qualified ones). str(PriceUnit) is byte-identical to the
+        # equivalent canonical string, so numeric behaviour is unchanged.
+        if isinstance(from_unit, PriceUnit):
+            from_unit = str(from_unit)
+        if isinstance(to_unit, PriceUnit):
+            to_unit = str(to_unit)
+
+        # Normalize, then split rate units with the single PriceUnit parser
+        # (quantity leg + rate period). No private rate parser anymore.
         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)
-
-        # Get base units
-        from_base = from_rate["base"]
-        to_base = to_rate["base"]
+        from_pu = PriceUnit.parse(from_unit)
+        to_pu = PriceUnit.parse(to_unit)
+        from_base = _to_pint_token(from_pu.quantity_unit)
+        to_base = _to_pint_token(to_pu.quantity_unit)
+        from_period = from_pu.period
+        to_period = to_pu.period
 
-        # Create quantity
         if isinstance(value, pd.Series):
-            result = self._convert_series(
-                value,
-                from_base,
-                to_base,
-                commodity,
-                from_rate["period"],
-                to_rate["period"],
+            # Series keeps the calendar-aware days_in_month path (pint's
+            # fixed-length month can't express it).
+            return self._convert_series(
+                value, from_base, to_base, commodity, from_period, to_period
             )
-        else:
-            result = self._convert_scalar(value, from_base, to_base, commodity)
-            if from_rate["period"] or to_rate["period"]:
-                factor = self._rate_factor_scalar(
-                    from_rate["period"], to_rate["period"]
-                )
-                result = result * factor
 
+        # Scalar: the base-unit factor goes through the SAME _convert_scalar path
+        # as a non-rate conversion (so a rate result is consistent-by-construction
+        # with the base one), multiplied by the period ratio. That ratio comes
+        # from pint's own calendar month/year lengths, replacing the deleted
+        # hand-rolled duplicates of those constants.
+        result = self._convert_scalar(value, from_base, to_base, commodity)
+        if from_period or to_period:
+            result = result * self._period_rate_factor(from_period, to_period)
         return result
 
     @lru_cache(maxsize=128)
@@ -466,7 +447,7 @@ class CommodityConverter:
         """Convert a pandas Series with optional rate handling.
 
         - Month conversions use the index's actual days_in_month when available.
-        - Other time conversions use standard averages (365.25 days/year, 30.4375 days/month).
+        - Other time conversions use pint's calendar period lengths.
         """
         result = series.copy()
 
@@ -483,9 +464,9 @@ class CommodityConverter:
                     else:
                         result = result / series.index.days_in_month
                 else:
-                    # Fallback to scalar factor for other period conversions
-                    factor = self._rate_factor_scalar(from_period, to_period)
-                    result = result * factor
+                    # Other period conversions (e.g. year<->day): pint's ratio
+                    # of period lengths.
+                    result = result * self._period_rate_factor(from_period, to_period)
 
         # Apply unit conversion
         factor_units = self._convert_scalar(1.0, from_unit, to_unit, commodity)
@@ -493,53 +474,24 @@ class CommodityConverter:
 
         return result
 
-    def _parse_rate_unit(self, unit: str) -> dict:
-        """Parse units like 'bbl/day' or 'kt/month'."""
-        if "/" in unit:
-            base, period = unit.split("/", 1)
-            base = _to_pint_token(base)
-            period = period.strip().lower().rstrip("s")  # day(s), month(s), year(s)
-            return {"base": base, "period": period}
-        return {"base": _to_pint_token(unit), "period": None}
-
-    def _rate_factor_scalar(
+    def _period_rate_factor(
         self, from_period: Optional[str], to_period: Optional[str]
     ) -> float:
-        """Scalar factor to convert between rate periods for scalars.
-
-        Uses average calendar lengths when months/years are involved.
-        - Average days per year: 365.25
-        - Average days per month: 365.25 / 12 = 30.4375
+        """Ratio converting a per-``from_period`` rate to per-``to_period``,
+        derived from pint's calendar period lengths (day/month/year) — the
+        single source that replaces the deleted hand-rolled constants. A
+        ``None`` period on either side is a no-op (1.0), matching historical
+        behaviour.
+
+        Feeds both the scalar path (period factor) and the Series non-month
+        path; the calendar-aware month<->day Series case is handled separately
+        with days_in_month.
         """
-        if from_period == to_period:
-            return 1.0
-        if from_period is None and to_period is None:
-            return 1.0
-        if from_period is None or to_period is None:
-            # Ambiguous to add/remove a time dimension for scalar; no-op to preserve behavior
+        if from_period == to_period or from_period is None or to_period is None:
             return 1.0
-
-        avg_days_per_year = 365.25
-        avg_days_per_month = avg_days_per_year / 12.0
-
-        # Helper to express rates as per-day factors
-        def per_day_factor(period: str) -> float:
-            if period == "day":
-                return 1.0
-            if period == "year":
-                return 1.0 / avg_days_per_year
-            if period == "month":
-                return 1.0 / avg_days_per_month
-            # Fallback to Pint if it's a known time unit
-            try:
-                return (1 * (self.ureg(period) ** -1)).to(self.ureg.day**-1).magnitude
-            except Exception:
-                raise ValueError(f"Unsupported rate period: {period}")
-
-        from_per_day = per_day_factor(from_period)
-        to_per_day = per_day_factor(to_period)
-        # Convert from per-from_period to per-to_period
-        return from_per_day / to_per_day
+        from_days = (1 * self.ureg(from_period)).to("day").magnitude
+        to_days = (1 * self.ureg(to_period)).to("day").magnitude
+        return to_days / from_days
 
     def _is_energy(self, unit: str) -> bool:
         return self.ureg(unit).check("[energy]")
@@ -605,13 +557,22 @@ converter = CommodityConverter()
 
 
 # Convenience functions for direct use
-def convert(value, from_unit: str, to_unit: str, commodity: Optional[str] = None):
-    """Convert values between units"""
+def convert(
+    value,
+    from_unit: Union[str, PriceUnit],
+    to_unit: Union[str, PriceUnit],
+    commodity: Optional[str] = None,
+):
+    """Convert values between units. Units may be strings or ``PriceUnit``."""
     return converter.convert(value, from_unit, to_unit, commodity)
 
 
-def convfactor(from_unit: str, to_unit: str, commodity: Optional[str] = None) -> float:
-    """Get conversion factor between units"""
+def convfactor(
+    from_unit: Union[str, PriceUnit],
+    to_unit: Union[str, PriceUnit],
+    commodity: Optional[str] = None,
+) -> float:
+    """Get conversion factor between units. Units may be strings or ``PriceUnit``."""
     return converter.convert(1.0, from_unit, to_unit, commodity)
 
 
@@ -624,10 +585,88 @@ def convfactor(from_unit: str, to_unit: str, commodity: Optional[str] = None) ->
 # 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: str,
-    to_unit: str,
+    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",
@@ -682,8 +721,20 @@ 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 = _currency.split_currency_unit(from_unit)
-    to_ccy, to_bare_unit = _currency.split_currency_unit(to_unit)
+    # 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).
@@ -740,67 +791,197 @@ def convert_price(
     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
-
-        if ffill_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 ffill_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: {ffill_policy!r} (expected 'strict' or 'ffill')"
-            )
-
+        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":
+        return value
+
+    # 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

{commodutil-4.4.0 → commodutil-4.6.0}/commodutil/standards/__init__.py

@@ -33,6 +33,9 @@ from commodutil.standards.currency import (
     split_currency_unit,
     to_symbol,
 )
+from commodutil.standards.price_unit import (
+    PriceUnit,
+)
 from commodutil.standards.price_units import (
     resolve_price_unit,
     resolve_price_unit_from_attrs,
@@ -81,6 +84,8 @@ __all__ = [
     "required_fx_pair",
     "split_currency_unit",
     "to_symbol",
+    # price_unit
+    "PriceUnit",
     # price_units
     "resolve_price_unit",
     "resolve_price_unit_from_attrs",