commodutil 4.4.0__tar.gz → 4.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.4.0
+Version: 4.5.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.5.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,6 +287,16 @@ class CommodityConverter:
             # With pandas Series and daily rates
             convert(series, 'kt/month', 'bbl/day', commodity='gasoline')
         """
+        # 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 and parse units to handle daily/monthly rates
         from_unit = _to_pint_token(from_unit)
         to_unit = _to_pint_token(to_unit)
@@ -605,13 +588,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)
 
 
@@ -626,8 +618,8 @@ def convfactor(from_unit: str, to_unit: str, commodity: Optional[str] = None) ->
 
 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 +674,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).
@@ -801,6 +805,92 @@ def convert_price(
     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
+
+
 def list_commodities():
     """List all available commodities"""
     return converter.available_commodities

{commodutil-4.4.0 → commodutil-4.5.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",

commodutil-4.5.0/commodutil/standards/price_unit.py

@@ -0,0 +1,163 @@
+"""commodutil.standards.price_unit: the ``PriceUnit`` value type.
+
+A ``PriceUnit`` is the structured form of a price-unit string such as
+``'USD/bbl'``, ``'GBp/therm'``, ``'kt/month'`` or a bare ``'bbl'``. It splits a
+quote into three independently-usable legs:
+
+* ``currency``      — canonical currency token per ``standards.currency``
+                      (``'USD'``, ``'GBp'``, ``'$'``, ...), or ``None`` for a
+                      bare / rate-only unit.
+* ``quantity_unit`` — the bare physical unit token (``'bbl'``, ``'MWh'`` ...).
+* ``period``        — the rate period for forms like ``'bbl/day'`` (``'day'`` /
+                      ``'month'`` / ``'year'``), or ``None``.
+
+Design goals (conversion-architecture-plan.md, Phase 3.1):
+
+* ``PriceUnit.parse(str(pu)) == pu`` is guaranteed for any ``PriceUnit`` — the
+  string form is canonical and losslessly round-trips.
+* ``parse`` is built directly on ``standards.currency.split_currency_unit`` plus
+  the same rate-suffix logic ``convfactors`` uses, so the legs it produces are
+  byte-for-byte what those callers computed before — letting ``convert`` /
+  ``convert_price`` adopt it at the boundary with zero behaviour change.
+* The **currency leg is usable on its own** (``major_currency``,
+  ``fractional_divisor``), which is what lets a currency-only conversion (USc ->
+  USD) succeed even when the quantity denominator is non-physical/unknown (the
+  RIN class of bug — see ``convfactors.convert_currency_leg``).
+
+Pure stdlib: depends only on ``standards.currency`` (itself pure stdlib). No
+pint, no pandas.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Union
+
+from commodutil.standards.currency import (
+    FRACTIONAL_CURRENCY_DIVISORS,
+    fractional_to_major,
+    split_currency_unit,
+)
+
+
+@dataclass(frozen=True)
+class PriceUnit:
+    """Immutable, structured representation of a price-unit string.
+
+    See module docstring. Construct directly with canonical legs or, more
+    commonly, via :meth:`parse`. Directly-constructed instances are normalised
+    (whitespace stripped; period lower-cased and de-pluralised; empty strings
+    coerced to ``None``) so equality and the round-trip guarantee hold
+    regardless of how the instance was built.
+    """
+
+    currency: Optional[str] = None
+    quantity_unit: str = ""
+    period: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        # frozen dataclass -> mutate via object.__setattr__ during init only.
+        object.__setattr__(self, "quantity_unit", str(self.quantity_unit).strip())
+        if self.currency is not None:
+            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).
+            period = str(self.period).strip().lower().rstrip("s")
+            object.__setattr__(self, "period", period or None)
+
+    # ---- construction -----------------------------------------------------
+
+    @classmethod
+    def parse(cls, text: Union["PriceUnit", str]) -> "PriceUnit":
+        """Parse a price-unit string into a ``PriceUnit``.
+
+        Handles every form the codebase round-trips today:
+          * bare unit:            ``'bbl'``, ``'MMBtu'``, ``'m^3'``
+          * rate unit:            ``'bbl/day'``, ``'kt/month'`` (currency=None)
+          * currency-qualified:   ``'USD/bbl'``, ``'GBp/therm'``, ``'$/bbl'``
+          * currency + rate:      ``'USD/bbl/day'`` (accepted for completeness;
+            not currently emitted anywhere in the codebase)
+
+        A currency prefix is recognised only when it is a valid token per
+        ``standards.currency`` (via ``split_currency_unit``), so a bare rate
+        unit like ``'bbl/day'`` is NOT mis-parsed as currency ``'bbl'`` — it
+        stays quantity ``'bbl'`` / period ``'day'``.
+
+        Passing an existing ``PriceUnit`` returns it unchanged.
+        """
+        if isinstance(text, cls):
+            return text
+        if text is None:
+            raise ValueError("PriceUnit.parse requires a non-None unit string")
+        raw = str(text).strip()
+        if not raw:
+            raise ValueError("PriceUnit.parse requires a non-empty unit string")
+
+        # split_currency_unit returns ('', raw) when the prefix is not a valid
+        # currency token, leaving bare rate units intact.
+        currency, bare = split_currency_unit(raw)
+        quantity_unit, period = cls._split_period(bare)
+        return cls(
+            currency=currency or None, quantity_unit=quantity_unit, period=period
+        )
+
+    @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."""
+        if "/" in bare:
+            base, _, period = bare.partition("/")
+            period = period.strip().lower().rstrip("s")
+            return base.strip(), (period or None)
+        return bare.strip(), None
+
+    # ---- string form ------------------------------------------------------
+
+    def __str__(self) -> str:
+        denom = self.quantity_unit
+        if self.period:
+            denom = f"{denom}/{self.period}"
+        if self.currency:
+            return f"{self.currency}/{denom}"
+        return denom
+
+    # ---- leg accessors ----------------------------------------------------
+
+    def currency_leg(self) -> Optional[str]:
+        """The currency token, or ``None`` for a bare/rate-only unit."""
+        return self.currency
+
+    def quantity_leg(self) -> str:
+        """The full quantity denominator string (unit plus any rate period).
+
+        Byte-identical to the bare-unit element returned by
+        ``standards.currency.split_currency_unit`` — e.g. ``'bbl'`` for
+        ``'USD/bbl'``, ``'bbl/day'`` for ``'bbl/day'``.
+        """
+        denom = self.quantity_unit
+        if self.period:
+            denom = f"{denom}/{self.period}"
+        return denom
+
+    @property
+    def is_currency_qualified(self) -> bool:
+        """True when a currency leg is present."""
+        return self.currency is not None
+
+    @property
+    def major_currency(self) -> Optional[str]:
+        """The parent major currency (USc -> USD, GBp -> GBP, $ -> USD), or
+        ``None`` when there is no currency leg."""
+        if not self.currency:
+            return None
+        return fractional_to_major(self.currency)
+
+    @property
+    def fractional_divisor(self) -> float:
+        """Divisor lifting a fractional-currency quote to its major unit
+        (GBp/USc/... -> 100.0); 1.0 for major or absent currencies."""
+        return FRACTIONAL_CURRENCY_DIVISORS.get(self.currency, 1.0)
+
+
+__all__ = ["PriceUnit"]