commodutil 4.5.0__tar.gz → 4.6.0__tar.gz

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

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

@@ -297,34 +297,32 @@ class CommodityConverter:
         if isinstance(to_unit, PriceUnit):
             to_unit = str(to_unit)
 
-        # Normalize and parse units to handle daily/monthly rates
+        # 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)
+        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
 
-        # Get base units
-        from_base = from_rate["base"]
-        to_base = to_rate["base"]
-
-        # 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)
@@ -449,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()
 
@@ -466,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)
@@ -476,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]")
@@ -616,6 +585,84 @@ def convfactor(
 # 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],
@@ -744,62 +791,9 @@ 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
@@ -891,6 +885,103 @@ def convert_currency_leg(
     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.5.0 → commodutil-4.6.0}/commodutil/standards/price_unit.py

@@ -62,7 +62,7 @@ class PriceUnit:
             currency = str(self.currency).strip()
             object.__setattr__(self, "currency", currency or None)
         if self.period is not None:
-            # Mirror convfactors._parse_rate_unit: day(s)/month(s)/year(s).
+            # Rate-period normalisation: day(s)/month(s)/year(s) -> singular.
             period = str(self.period).strip().lower().rstrip("s")
             object.__setattr__(self, "period", period or None)
 
@@ -104,8 +104,8 @@ class PriceUnit:
 
     @staticmethod
     def _split_period(bare: str) -> tuple[str, Optional[str]]:
-        """Split a bare unit into (quantity_unit, period), mirroring
-        convfactors._parse_rate_unit's period handling."""
+        """Split a bare unit into (quantity_unit, period) with day(s)/month(s)/
+        year(s) rate-period normalisation."""
         if "/" in bare:
             base, _, period = bare.partition("/")
             period = period.strip().lower().rstrip("s")

{commodutil-4.5.0 → commodutil-4.6.0}/commodutil.egg-info/PKG-INFO

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

@@ -45,6 +45,7 @@ commodutil/standards/unit_registry.py
 commodutil/standards/units.py
 tests/__init__.py
 tests/conftest.py
+tests/test_align_fx_result.py
 tests/test_arb.py
 tests/test_cl.csv
 tests/test_conv.py
@@ -54,6 +55,7 @@ tests/test_golden_factors.py
 tests/test_pandasutils.py
 tests/test_price_conv.py
 tests/test_price_unit.py
+tests/test_rate_pint.py
 tests/test_standards_analysis_types.py
 tests/test_standards_commodities.py
 tests/test_standards_commodity_groups.py

{commodutil-4.5.0 → commodutil-4.6.0}/commodutil.egg-info/scm_file_list.json

@@ -8,10 +8,12 @@
     "requirements_dev.txt",
     ".gitignore",
     ".pypirc",
+    "tests/test_rate_pint.py",
     "tests/__init__.py",
     "tests/test_dates.py",
     "tests/test_price_unit.py",
     "tests/test_standards_analysis_types.py",
+    "tests/test_align_fx_result.py",
     "tests/test_standards_price_units.py",
     "tests/test_standards_commodities.py",
     "tests/test_standards_commodity_groups.py",

{commodutil-4.5.0 → commodutil-4.6.0}/commodutil.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "4.5.0",
+  "tag": "4.6.0",
   "distance": 0,
-  "node": "g5738049a36890f22f52027e9b93bf094f462689e",
+  "node": "g53c22a462207c9d8759c79cb652fec7690b4b98e",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-07-02"

commodutil-4.6.0/tests/test_align_fx_result.py

@@ -0,0 +1,130 @@
+"""Phase 3.4 tests: align_fx (extracted) and convert_price_result (additive).
+
+convert_price itself is unchanged (its behaviour is pinned by the golden fixture
+and the existing tests/test_price_conv.py). These cover the new public surface:
+the extracted align_fx helper and the result-bearing convert_price_result.
+"""
+
+import logging
+
+import pandas as pd
+import pytest
+
+from commodutil import convfactors
+from commodutil.convfactors import ConversionResult
+
+
+# ---- align_fx direct (mirrors the convert_price fx alignment tests) ----
+
+
+def test_align_fx_strict_raises_on_pre_start():
+    fx = pd.Series([1.10, 1.11, 1.12], index=pd.date_range("2026-01-05", periods=3))
+    idx = pd.date_range("2026-01-01", periods=3)  # entirely before fx start
+    with pytest.raises(ValueError, match="FX missing or stale"):
+        convfactors.align_fx(fx, idx, policy="strict")
+
+
+def test_align_fx_strict_within_staleness_ok():
+    fx = pd.Series([1.07, 1.08, 1.09], index=pd.date_range("2026-01-01", periods=3))
+    idx = pd.date_range("2026-01-01", periods=5)  # 2 days past fx end, within 7d
+    out = convfactors.align_fx(fx, idx, policy="strict")
+    assert out.isna().sum() == 0
+    assert out.iloc[-1] == pytest.approx(1.09)  # forward-filled within staleness
+
+
+def test_align_fx_ffill_warns_and_fills(caplog):
+    fx = pd.Series([1.10, 1.11, 1.12], index=pd.date_range("2026-01-05", periods=3))
+    idx = pd.date_range("2026-01-01", periods=3)  # pre-start
+    with caplog.at_level(logging.WARNING, logger="commodutil.convfactors"):
+        out = convfactors.align_fx(fx, idx, policy="ffill")
+    assert out.isna().sum() == 0
+    assert any("ffill_policy='ffill'" in rec.message for rec in caplog.records)
+
+
+def test_align_fx_ffill_all_nan_raises():
+    fx = pd.Series([float("nan")] * 3, index=pd.date_range("2026-01-01", periods=3))
+    idx = pd.date_range("2026-01-01", periods=3)
+    with pytest.raises(ValueError, match="entirely NaN"):
+        convfactors.align_fx(fx, idx, policy="ffill")
+
+
+def test_align_fx_unknown_policy_raises():
+    fx = pd.Series([1.07], index=pd.date_range("2026-01-01", periods=1))
+    with pytest.raises(ValueError, match="Unknown ffill_policy"):
+        convfactors.align_fx(fx, fx.index, policy="bogus")
+
+
+def test_align_fx_matches_convert_price_series_path():
+    # convert_price delegates to align_fx; a manual compose reproduces it.
+    idx = pd.date_range("2026-01-01", periods=3)
+    p = pd.Series([35.0, 36.5, 34.2], index=idx)
+    fx = pd.Series([1.07, 1.08, 1.06], index=idx)
+    via_cp = convfactors.convert_price(p, "EUR/MWh", "USD/MMBtu", fx=fx)
+    factor = convfactors.convfactor("MWh", "MMBtu")
+    fx_aligned = convfactors.align_fx(fx, p.index)
+    manual = (p / factor) * fx_aligned  # EUR major, divisor 1.0
+    pd.testing.assert_series_equal(via_cp, manual)
+
+
+# ---- convert_price_result ----
+
+_SAMPLE = [
+    (100.0, "mt", "bbl", "gasoline", None),
+    (2.5, "gal", "bbl", None, None),
+    (250.0, "USc/gal", "USD/gal", None, None),
+    (100.0, "USD/mt", "USD/bbl", "diesel", None),
+    (35.0, "EUR/MWh", "USD/MMBtu", None, 1.07),
+    (80.0, "GBp/therm", "USD/MMBtu", None, 1.25),
+]
+
+
+def test_convert_price_result_value_matches_convert_price():
+    for value, frm, to, commodity, fx in _SAMPLE:
+        res = convfactors.convert_price_result(value, frm, to, commodity, fx=fx)
+        expected = convfactors.convert_price(value, frm, to, commodity, fx=fx)
+        assert isinstance(res, ConversionResult)
+        assert res.value == pytest.approx(expected, rel=1e-12)
+        assert res.applied is True
+        assert res.note.startswith("convert_price:")
+
+
+def test_convert_price_result_is_frozen():
+    res = convfactors.convert_price_result(2.5, "gal", "bbl")
+    with pytest.raises(Exception):
+        res.value = 0.0  # frozen dataclass
+
+
+def test_convert_price_result_identity_unchanged():
+    res = convfactors.convert_price_result(100.0, "USD/bbl", "USD/bbl")
+    assert res.value == 100.0
+    assert res.applied is False
+    assert res.note == "unchanged"
+
+
+def test_convert_price_result_currency_leg_fallback_rin():
+    # convert_price can't do convfactor('RIN','RIN'); the fallback applies the
+    # pure currency scale and records the currency_leg route.
+    res = convfactors.convert_price_result(250.0, "USc/RIN", "USD/RIN")
+    assert res.value == pytest.approx(2.5, rel=1e-12)
+    assert res.applied is True
+    assert res.note.startswith("currency_leg:")
+
+
+def test_convert_price_result_keep_raw_on_unconvertible():
+    # Different, pint-unknown denominators: no route works -> keep-raw.
+    res = convfactors.convert_price_result(100.0, "GBp/XYZ", "USD/ABC", on_error="keep")
+    assert res.value == 100.0
+    assert res.applied is False
+    assert res.note.startswith("kept-raw:")
+
+
+def test_convert_price_result_raise_is_default():
+    with pytest.raises(Exception):
+        convfactors.convert_price_result(100.0, "GBp/XYZ", "USD/ABC")
+
+
+def test_convert_price_result_invalid_on_error():
+    with pytest.raises(ValueError, match="on_error must be"):
+        convfactors.convert_price_result(
+            1.0, "USD/mt", "USD/bbl", "diesel", on_error="x"
+        )

commodutil-4.6.0/tests/test_rate_pint.py

@@ -0,0 +1,81 @@
+"""Phase 3.3 tests: rate conversions lean on pint (separable design).
+
+The hand-rolled scalar rate machinery (_parse_rate_unit / _rate_factor_scalar)
+is deleted. A rate conversion is now the base-unit factor (the SAME
+_convert_scalar path as a non-rate conversion) times a period ratio derived from
+pint's calendar lengths (_period_rate_factor), so the calendar constants are no
+longer duplicated. The Series path keeps calendar-aware days_in_month. Both are
+fed by the single PriceUnit parser. Numerics are pinned by the golden fixture;
+these tests assert the structural change and preserved edge behaviours.
+"""
+
+import inspect
+import re
+
+import pandas as pd
+import pytest
+
+from commodutil import convfactors
+
+
+def test_hand_rolled_rate_machinery_deleted():
+    converter = convfactors.converter
+    assert not hasattr(converter, "_parse_rate_unit")
+    assert not hasattr(converter, "_rate_factor_scalar")
+
+
+def test_no_hardcoded_calendar_constants_in_convfactors():
+    # The dedup guarantee: pint is the single source of month/year lengths, so
+    # the old literals must not reappear anywhere in the module.
+    src = inspect.getsource(convfactors)
+    assert "30.4375" not in src
+    assert not re.search(r"\b365\.25\b", src)
+
+
+def test_rate_consistent_with_base_factor_times_pint_ratio():
+    # Rate result == base-unit factor x pint period ratio, for the golden
+    # commodities. Proves the separable design and that the ratio is pint's.
+    month_len = (1 * convfactors.ureg("month")).to("day").magnitude
+    for commodity in ("crude", "diesel", "gasoline", "fuel_oil"):
+        base = convfactors.convfactor("kt", "bbl", commodity)
+        rate = convfactors.convert(1.0, "kt/month", "bbl/day", commodity)
+        assert rate == pytest.approx(base / month_len, rel=1e-12), commodity
+
+
+def test_scalar_rate_uses_pint_calendar_constants():
+    # pint's month=30.4375d, year=365.25d — the exact constants the deleted
+    # code hand-rolled.
+    assert convfactors.convert(1.0, "bbl/day", "bbl/month") == pytest.approx(
+        30.4375, rel=1e-12
+    )
+    assert convfactors.convert(1.0, "bbl/day", "bbl/year") == pytest.approx(
+        365.25, rel=1e-12
+    )
+
+
+def test_none_commodity_rate_raises_bare_unit_message():
+    # Error messages are preserved character-for-character (bare units, not the
+    # rate form) — these are the two pinned golden rate errors.
+    with pytest.raises(ValueError, match=r"^Commodity required for kt to bbl$"):
+        convfactors.convert(1.0, "kt/month", "bbl/day")
+    with pytest.raises(ValueError, match=r"^Commodity required for bbl to mt$"):
+        convfactors.convert(1.0, "bbl/day", "mt/year")
+
+
+def test_series_month_aware_uses_calendar_days():
+    # The Series path keeps calendar-aware days_in_month (2020 is a leap year,
+    # so February has 29 days) — pint's fixed-length month cannot express this.
+    dates = pd.date_range("2020-01-01", periods=3, freq="MS")  # Jan, Feb, Mar 2020
+    s = pd.Series([100.0, 100.0, 100.0], index=dates)  # kt/month
+    out = convfactors.convert(s, "kt/month", "bbl/day", "diesel")
+    kt_to_bbl = convfactors.convfactor("kt", "bbl", "diesel")
+    assert out.iloc[0] == pytest.approx(100 * kt_to_bbl / 31, abs=1)  # Jan 31d
+    assert out.iloc[1] == pytest.approx(100 * kt_to_bbl / 29, abs=1)  # Feb 29d (leap)
+    assert out.iloc[2] == pytest.approx(100 * kt_to_bbl / 31, abs=1)  # Mar 31d
+
+
+def test_series_non_month_period_matches_pint_ratio():
+    # A calendar-unaware index falls back to the pint period ratio (year->day).
+    s = pd.Series([365250.0, 365250.0])  # RangeIndex, no days_in_month
+    out = convfactors.convert(s, "bbl/year", "bbl/day")
+    assert out.iloc[0] == pytest.approx(1000.0, abs=1e-6)