commodutil 4.5.0__tar.gz → 4.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.5.0
+Version: 4.7.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.7.0}/commodutil/convfactors.py

@@ -131,8 +131,8 @@ COMMODITIES = {
         "naphtha", 0.706720311 * ureg.kg / ureg.L, 34.826266 * ureg.GJ / ureg.m**3
     ),  # HHV; EIA petrochemical naphtha <401F 5.248 MMBtu/bbl -> 49.28 GJ/t gross (was NCV 44.90)
     "ethanol": Commodity(
-        "ethanol", 0.755079324 * ureg.kg / ureg.L, 23.485167 * ureg.GJ / ureg.m**3
-    ),  # HHV; EIA fuel ethanol (undenatured) 3.539 MMBtu/bbl -> 31.10 GJ/t gross (was net ~27.81); NOTE density 0.7551 looks copied from gasoline (ethanol ~0.789) - flagged, left unchanged
+        "ethanol", 0.7937 * ureg.kg / ureg.L, 23.485167 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA fuel ethanol (undenatured) 3.539 MMBtu/bbl. Density: ASTM D4806 undenatured fuel ethanol SG 60/60F lower bound 0.7937 (Energy Transfer spec note; IEA AMF rounds ethanol density to 0.79 kg/L). Energy_content is per-volume, so bbl->MMBtu stays fixed while mt factors move.
     # Middle distillates
     "diesel": Commodity(
         "diesel", 0.844269902 * ureg.kg / ureg.L, 38.290312 * ureg.GJ / ureg.m**3
@@ -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.7.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.7.0}/commodutil/standards/unit_registry.py

@@ -203,16 +203,25 @@ UNIT_ROWS: Tuple[UnitRow, ...] = (
         # into UNIT_MAP. A prefix like 'cubic met' does NOT work under
         # word-boundary matching (trailing letters kill the lookahead), so each
         # form is listed explicitly.
+        #
+        # Phase 2.1 residual consolidation: the bare notations 'm3' / 'm^3' /
+        # 'm**3' are PROMOTED from public_only into UNIT_MAP so curvemetadata's
+        # word-boundary parse_unit resolves them directly and its local
+        # _EXTRA_UNIT_ALIASES fallback can be deleted. Word-boundary safe: 'm3'
+        # cannot match inside 'm30' (trailing [0-9] kills the lookahead); the
+        # '**'/'^' chars are regex-escaped by parse_unit. Purely additive to
+        # UNIT_MAP; PUBLIC_UNIT_MAP is unchanged (a UNIT_MAP entry is inherited
+        # by PUBLIC_UNIT_MAP either way).
         unit_map_spellings=(
             "cubic meter",
             "cubic meters",
             "cubic metre",
             "cubic metres",
-        ),
-        public_only_spellings=(
             "m3",
             "m^3",
             "m**3",
+        ),
+        public_only_spellings=(
             "cubic_meter",
             "cubic_meters",
             "cubic_metre",
@@ -222,8 +231,13 @@ UNIT_ROWS: Tuple[UnitRow, ...] = (
     UnitRow(
         "kg",
         "mass",
-        # curvemetadata: kg / kilogram(s) / kilogramme(s)
-        public_only_spellings=(
+        # Phase 2.1 residual consolidation: kg / kilogram(s) / kilogramme(s)
+        # PROMOTED from public_only into UNIT_MAP so parse_unit resolves them and
+        # curvemetadata's _EXTRA_UNIT_ALIASES fallback can be deleted. The
+        # numeric-prefixed scaled form ("25,000 kg") stays a curvemetadata-local
+        # regex (its no-space variant "25000kg" is unreachable by word-boundary
+        # matching). Additive to UNIT_MAP; PUBLIC_UNIT_MAP unchanged.
+        unit_map_spellings=(
             "kg",
             "kilogram",
             "kilograms",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.5.0
+Version: 4.7.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.7.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.7.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.7.0/commodutil.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "4.7.0",
+  "distance": 0,
+  "node": "ge71901f8d2006cfe2abbc815edbbf7d645edfb3a",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-03"
+}