commodutil 4.3.2__tar.gz → 4.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.3.2
+Version: 4.4.0
 Summary: common commodity/oil analytics utils
 Author-email: aeorxc <author@example.com>
 Project-URL: Homepage, https://dev.azure.com/RWEST-MFI-TE/Oil/_git/commodutil
@@ -9,9 +9,10 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
-Requires-Dist: pandas
+Requires-Dist: pandas>=2.1
 Requires-Dist: dask[delayed]
 Requires-Dist: pint
+Requires-Dist: python-dateutil
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-runner; extra == "test"

{commodutil-4.3.2 → commodutil-4.4.0}/commodutil/__init__.py

@@ -38,7 +38,9 @@ _LAZY_EXPORTS = {
     "normalize_currency_token": "commodutil.standards.currency",
     "split_currency_unit": "commodutil.standards.currency",
     # standards.units (stdlib-only -- cheap, no pint)
+    "canonical_price_unit_token": "commodutil.standards.units",
     "canonical_quantity_unit": "commodutil.standards.units",
+    "canonical_unit_token": "commodutil.standards.units",
     "quantity_unit_from_price_unit": "commodutil.standards.units",
     # dates
     "curmon": "commodutil.dates",

{commodutil-4.3.2 → commodutil-4.4.0}/commodutil/convfactors.py

@@ -16,7 +16,17 @@ from commodutil.standards.units import to_pint_token as _to_pint_token
 
 logger = logging.getLogger(__name__)
 
-# Initialize pint with custom definitions
+# Initialize pint with custom definitions.
+#
+# NOTE: kept case-sensitive on purpose. `pint.UnitRegistry(case_sensitive=False)`
+# looks tempting (it would drop the hand-registered casing aliases below), but it
+# is UNSAFE for this registry: pint's case-folded lookup makes our domain units
+# collide with SI units that differ only by case -- `kt`/`mt`/`gal` vs `kT`/`mT`
+# (kilo/milli-tesla, T = tesla) and `Gal` (galileo, cm/s^2), while lowercase
+# `mw`/`mwh` resolve to milli-watt instead of mega-. Collision winners are chosen
+# from a set and are NON-DETERMINISTIC (PYTHONHASHSEED-dependent), so `kt`->`km3`
+# etc. intermittently raise "incompatible dimensions". We therefore register the
+# exact spellings we need explicitly and leave the registry case-sensitive.
 ureg = pint.UnitRegistry()
 
 # Define oil & gas specific units.
@@ -74,62 +84,113 @@ class Commodity:
     mass<->volume conversion is undefined and must raise).
     Previously this used `0.0 kg/L` as a sentinel; magnitude==0 checks
     were scattered through the codebase. `None` makes the intent explicit.
+
+    `energy_content` may be a pint Quantity of EITHER dimensionality:
+      - `[energy]/[volume]` (e.g. GJ/m^3) — the default for liquids; registers a
+        `[volume] <-> [energy]` transformation (and chains to mass via density).
+      - `[energy]/[mass]` (e.g. GJ/t) — for density-less solids like coal;
+        registers a DIRECT `[mass] <-> [energy]` transformation so `mt <-> MMBtu`
+        works with `density=None`, while `mt <-> bbl` still correctly raises.
+    A bare float is coerced to the volume-basis default (GJ/m^3) for back-compat.
     """
 
     name: str
     density: Optional[pint.Quantity] = None  # kg/L or API gravity; None = not a liquid
-    energy_content: Optional[pint.Quantity] = None  # GJ/m^3 or similar
+    # [energy]/[volume] (GJ/m^3, liquids) OR [energy]/[mass] (GJ/t, e.g. coal)
+    energy_content: Optional[pint.Quantity] = None
 
     def __post_init__(self):
         # Ensure quantities have correct dimensions
         if self.density is not None and not isinstance(self.density, pint.Quantity):
             self.density = self.density * ureg.kg / ureg.liter
-        if self.energy_content and not isinstance(self.energy_content, pint.Quantity):
+        # Bare float -> volume-basis default (GJ/m^3). Callers wanting a mass
+        # basis pass an explicit Quantity (e.g. `26.377 * ureg.GJ / ureg.mt`),
+        # which is left untouched here and dispatched on in _commodity_context.
+        if self.energy_content is not None and not isinstance(
+            self.energy_content, pint.Quantity
+        ):
             self.energy_content = self.energy_content * ureg.GJ / ureg.m**3
 
 
+# -----------------------------------------------------------------------------
+# Calorific basis policy: GROSS (higher heating value, HHV).
+#
+# `energy_content` for every liquid commodity below is stated on a GROSS/HHV
+# basis, anchored on the U.S. EIA Monthly Energy Review Appendix A, Table A1
+# ("Approximate Heat Content of Petroleum and Biofuels", explicitly gross —
+# "Gross heat content rates are applied in all Btu calculations for the Monthly
+# Energy Review") and, for the NGL species, GPA/EIA figures (EIA A1 which cites
+# NIST enthalpy-of-combustion + API liquid densities). NGL/natural-gas hubs
+# (Henry Hub, TTF, NBP, JKM) all quote HHV, so a cross-fuel $/MMBtu comparison
+# is only internally consistent if every commodity is on the same gross basis.
+#
+# The stored value is GJ/m^3 (energy per unit VOLUME), set directly from the
+# EIA gross figure in MMBtu/bbl via the fixed, density-independent conversion
+#     GJ/m^3 = MMBtu/bbl * 1.055056 GJ/MMBtu / 0.158987294928 m^3/bbl
+# so that convfactor('bbl','MMBtu', <commodity>) reproduces the EIA number
+# exactly. Densities are NOT part of this conversion; they remain the
+# BP/Energy-Institute values unchanged (the resulting GJ/t is therefore a
+# derived reporting figure = energy_content / density). Each entry's comment
+# records the source EIA MMBtu/bbl figure and the implied gross GJ/t.
+#
+# Historical note: several products (diesel/naphtha/jet/gasoline/fuel_oil) and
+# the biofuels previously carried BP-style NET (NCV) energy contents, which
+# understated $/MMBtu by ~1-12% vs gross. Standardising on gross was the
+# owner-approved decision (conversion-architecture-plan.md, decision 2b).
+#
+# NOT covered by this policy (see per-entry comments / flagged for desk review):
+# crude (kept on its documented BP gross basis), the LPG/LNG blends (`lpg`,
+# `natgas`), gaseous `natural_gas`, and `product_basket` — all blend- or
+# construction-dependent rather than single-species EIA rows.
+# -----------------------------------------------------------------------------
 # Define commodities with their properties and correct industry factors
 COMMODITIES = {
     # Crude oil (BP approximate conversion factors)
     # 1 mt ≈ 7.33 bbl and ≈ 1.165 kL => density ≈ 0.85809 kg/L
-    "crude": Commodity("crude", 0.85809151 * ureg.kg / ureg.L, None),
+    "crude": Commodity(
+        "crude", 0.85809151 * ureg.kg / ureg.L, 39.043 * ureg.GJ / ureg.m**3
+    ),  # HHV; BP/EI ~45.5 GJ/t gross (implies 5.883 MMBtu/bbl). EIA Table A2 crude ~5.69-5.80 MMBtu/bbl (US, lighter) -> commodutil is ~1-3% higher; kept on documented BP world-crude gross basis, not changed
     # Light ends - tuned to match kbbl/kt figures exactly
     "gasoline": Commodity(
-        "gasoline", 0.755079324 * ureg.kg / ureg.L, 33.7898 * ureg.GJ / ureg.m**3
-    ),  # BP: 44.75 GJ/t
+        "gasoline", 0.755079324 * ureg.kg / ureg.L, 34.653728 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA motor gasoline blending components (2007+, GREET) 5.222 MMBtu/bbl -> 45.89 GJ/t gross (was BP NCV 44.75; RBOB/blendstock basis, not E10-finished ~5.05)
     "naphtha": Commodity(
-        "naphtha", 0.706720311 * ureg.kg / ureg.L, None
-    ),  # 8.90 kbbl/kt
+        "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, 21 * ureg.GJ / ureg.m**3
-    ),  # 8.33 kbbl/kt
+        "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
     # Middle distillates
     "diesel": Commodity(
-        "diesel", 0.844269902 * ureg.kg / ureg.L, 36.624428 * ureg.GJ / ureg.m**3
-    ),  # BP: 43.38 GJ/t
+        "diesel", 0.844269902 * ureg.kg / ureg.L, 38.290312 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA distillate (15 ppm & under) 5.770 MMBtu/bbl -> 45.35 GJ/t gross (was BP NCV 43.38)
     "jet": Commodity(
-        "jet", 0.798199336 * ureg.kg / ureg.L, 35.056915 * ureg.GJ / ureg.m**3
-    ),  # BP: 43.92 GJ/t
+        "jet", 0.798199336 * ureg.kg / ureg.L, 37.626702 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA jet fuel kerosene-type 5.670 MMBtu/bbl -> 47.14 GJ/t gross (was BP NCV 43.92)
     "fame": Commodity(
-        "fame", 0.892001564 * ureg.kg / ureg.L, 33 * ureg.GJ / ureg.m**3
-    ),  # 7.051345 kbbl/kt
+        "fame", 0.892001564 * ureg.kg / ureg.L, 35.562874 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA biodiesel 5.359 MMBtu/bbl -> 39.87 GJ/t gross (was net ~37.00)
     "hvo": Commodity(
-        "hvo", 0.781731391 * ureg.kg / ureg.L, 34 * ureg.GJ / ureg.m**3
-    ),  # 8.046 kbbl/kt
+        "hvo", 0.781731391 * ureg.kg / ureg.L, 36.458748 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA renewable diesel fuel 5.494 MMBtu/bbl -> 46.64 GJ/t gross (was net ~43.49)
     # Heavy products
     "vgo": Commodity("vgo", 0.911566778 * ureg.kg / ureg.L, None),  # 6.90 kbbl/kt
     "fuel_oil": Commodity(
-        "fuel_oil", 0.990521381 * ureg.kg / ureg.L, 41.175974 * ureg.GJ / ureg.m**3
-    ),  # BP: 41.57 GJ/t
+        "fuel_oil", 0.990521381 * ureg.kg / ureg.L, 41.721177 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA residual fuel oil 6.287 MMBtu/bbl -> 42.12 GJ/t gross (was BP NCV 41.57)
     # LPG and Natural gas (liquefied)
     "lpg": Commodity(
         "lpg", 0.541 * ureg.kg / ureg.L, 24.96715 * ureg.GJ / ureg.m**3
-    ),  # BP: LPG 46.15 GJ/t
+    ),  # BP: LPG 46.15 GJ/t (implies 3.762 MMBtu/bbl). FLAGGED: generic propane/butane blend; likely NET-basis, but the gross value is composition-dependent (undocumented mix) -> not changed. Desk: specify a C3/C4 split, or price via the discrete NGL species instead.
     "natgas": Commodity(
         "natgas", 0.542225066 * ureg.kg / ureg.L, 26.137 * ureg.GJ / ureg.m**3
-    ),
+    ),  # liquefied NG / LNG (alias 'lng'); implies 48.20 GJ/t, 3.939 MMBtu/bbl. FLAGGED: density 0.542 is high for LNG (~0.43-0.47) and basis is unclear -> not changed pending desk clarification of what this represents vs 'natural_gas'.
     # Natural gas (gaseous, pipeline): BP approx 36 PJ per bcm => 0.036 GJ/m**3
     # density=None: not a liquid, so mass<->volume conversion is undefined.
+    # FLAGGED (HHV policy): 0.036 GJ/m^3 (=36 MJ/m^3) is a rounded BP approx sitting
+    # between net (~34.6) and US-pipeline gross (~38.3 MJ/m^3, ~1028 Btu/scf). Not
+    # clearly net, and it has broad blast radius (bcm<->energy in many callers +
+    # explicit tests), so left unchanged; desk to confirm gross ~0.0383 if wanted.
     "natural_gas": Commodity(
         "natural_gas", density=None, energy_content=0.036 * ureg.GJ / ureg.m**3
     ),
@@ -138,23 +199,36 @@ COMMODITIES = {
     # $/gal <-> $/MMBtu for the MB OPIS futures (AC0, B0, AD0, A8I)).
     "ethane": Commodity(
         "ethane", 0.373 * ureg.kg / ureg.L, 18.4262 * ureg.GJ / ureg.m**3
-    ),  # BP: 49.4 GJ/t; 1 gal ~ 0.0661 MMBtu (HHV)
+    ),  # HHV; implies 2.777 MMBtu/bbl vs EIA ethane 2.783 (+0.2%, within tol) -> left as-is
     "propane": Commodity(
         "propane", 0.507 * ureg.kg / ureg.L, 25.5375 * ureg.GJ / ureg.m**3
-    ),  # ~91,690 BTU/gal HHV; ~50.35 GJ/t
+    ),  # HHV; implies 3.848 MMBtu/bbl vs EIA propane 3.841 (-0.2%, within tol) -> left as-is
     "butane": Commodity(
-        "butane", 0.574 * ureg.kg / ureg.L, 28.4400 * ureg.GJ / ureg.m**3
-    ),  # n-butane; ~103,000 BTU/gal HHV liquid; ~49.5 GJ/t
+        "butane", 0.574 * ureg.kg / ureg.L, 28.887 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA MER App A n-butane 4.353 MMBtu/bbl gross (was 28.44 -> 4.286 MMBtu/bbl, -1.57% off EIA; aligned 2026-07 per EIA-gross basis decision)
     "isobutane": Commodity(
         "isobutane", 0.557 * ureg.kg / ureg.L, 27.7700 * ureg.GJ / ureg.m**3
-    ),  # iso-C4; ~99,000 BTU/gal HHV liquid
+    ),  # HHV; implies 4.185 MMBtu/bbl vs EIA isobutane 4.183 (-0.0%, within tol) -> left as-is
     "natural_gasoline": Commodity(
-        "natural_gasoline", 0.6675 * ureg.kg / ureg.L, 31.4 * ureg.GJ / ureg.m**3
-    ),  # pentanes-plus; ~118,000 BTU/gal HHV
+        "natural_gasoline", 0.6675 * ureg.kg / ureg.L, 30.778 * ureg.GJ / ureg.m**3
+    ),  # HHV; EIA MER App A pentanes-plus 4.638 MMBtu/bbl gross (was 31.4 -> 4.732 MMBtu/bbl, +1.98% off EIA; aligned 2026-07 per EIA-gross basis decision)
     # BP product basket (optional reference)
     "product_basket": Commodity(
         "product_basket", 0.781 * ureg.kg / ureg.L, 33.642356 * ureg.GJ / ureg.m**3
-    ),
+    ),  # implies 43.08 GJ/t, 5.070 MMBtu/bbl. FLAGGED: weighted product basket, construction (component weights) undocumented -> not changed; should be recomputed from the now-gross component products with documented weights rather than guessed.
+    # Solid fuels: MASS-basis energy_content (GJ/t) with density=None. mt<->energy
+    # (the only meaningful jump, $/t <-> $/MMBtu) works; mt<->bbl stays illegal.
+    "coal": Commodity(
+        "coal",
+        density=None,
+        energy_content=26.377 * ureg.GJ / ureg.mt,
+    ),  # API2 CIF ARA thermal coal. GROSS/HHV basis: traded spec is 6,000 kcal/kg
+    # NAR (net); the gross equivalent is ~6,300 kcal/kg GAR (Argus/CoalIndo NAR/GAR
+    # markers show a ~300 kcal/kg NAR->GAR gap for high-rank export coal, e.g.
+    # 6,200 NAR = 6,500 GAR). 6,300 kcal/kg x 4.1868 kJ/kcal (IT calorie) = 26.377
+    # GJ/t = 25.00 MMBtu/t. Replaces the legacy /27.76 tce divisor in
+    # oilpricingcharts energy_mmbtu (generic tonne-of-coal-equivalent, 7,000 kcal/kg
+    # GCV = 29.29 GJ/t) which understated coal $/MMBtu by ~11%.
 }
 
 # Aliases for compatibility
@@ -270,97 +344,115 @@ class CommodityConverter:
 
         return result
 
+    @lru_cache(maxsize=128)
+    def _commodity_context(self, name: str) -> pint.Context:
+        """Build (and cache) a pint Context expressing a commodity's dimensional
+        transformations.
+
+        A commodity's physical properties define which cross-dimension jumps are
+        legal:
+          - ``density`` (kg/m^3) enables ``[mass] <-> [volume]``.
+          - ``energy_content`` on a VOLUME basis (J/m^3) enables
+            ``[volume] <-> [energy]`` (and chains to ``[mass] <-> [energy]`` via
+            density when present).
+          - ``energy_content`` on a MASS basis (J/kg) enables ``[mass] <-> [energy]``
+            DIRECTLY — for density-less solids (coal) whose only meaningful jump
+            is $/t <-> $/MMBtu. No volume transform is registered, so a
+            mass<->volume jump still finds no path and raises.
+        pint composes the registered transformations into a graph and finds the
+        conversion path itself — no manual branching on the path is needed.
+
+        Properties that are ``None`` register no transformation, so pint simply
+        finds no path and raises ``DimensionalityError`` (translated to a domain
+        ``ValueError`` by the caller). This is how density=None commodities
+        (natural_gas, naphtha, vgo) reject any mass<->volume(<->energy) jump.
+        """
+        comm = self.get_commodity(name)
+        ctx = pint.Context(comm.name)
+        if comm.density is not None:
+            d = comm.density.to("kg/m^3")
+            ctx.add_transformation("[mass]", "[volume]", lambda ureg, x, d=d: x / d)
+            ctx.add_transformation("[volume]", "[mass]", lambda ureg, x, d=d: x * d)
+        if comm.energy_content is not None:
+            ec = comm.energy_content
+            if ec.check("[energy]/[volume]"):
+                e = ec.to("J/m^3")
+                ctx.add_transformation(
+                    "[volume]", "[energy]", lambda ureg, x, e=e: x * e
+                )
+                ctx.add_transformation(
+                    "[energy]", "[volume]", lambda ureg, x, e=e: x / e
+                )
+            elif ec.check("[energy]/[mass]"):
+                em = ec.to("J/kg")
+                ctx.add_transformation(
+                    "[mass]", "[energy]", lambda ureg, x, em=em: x * em
+                )
+                ctx.add_transformation(
+                    "[energy]", "[mass]", lambda ureg, x, em=em: x / em
+                )
+            else:
+                raise ValueError(
+                    f"{comm.name}: energy_content must be [energy]/[volume] or "
+                    f"[energy]/[mass], got dimensionality {dict(ec.dimensionality)}"
+                )
+        return ctx
+
     def _convert_scalar(
         self, value: float, from_unit: str, to_unit: str, commodity: Optional[str]
     ) -> float:
-        """Convert a scalar value across mass/volume/energy using commodity context when needed."""
+        """Convert a scalar value across mass/volume/energy using a commodity's
+        pint Context when a cross-dimension jump is needed."""
         from_unit = _to_pint_token(from_unit)
         to_unit = _to_pint_token(to_unit)
         qty = value * self.ureg(from_unit)
 
-        # Try direct conversion first
+        # Same-dimension conversion (e.g. kt->mt, bbl->L): no commodity needed.
         try:
             return qty.to(to_unit).magnitude
         except DimensionalityError:
             pass
 
-        # Determine unit types
+        # Cross-dimensional: needs commodity physical properties. Decide the
+        # right error up front when no commodity was supplied (mirrors the
+        # historical messages the callers/tests grep for).
         is_from_energy = self._is_energy(from_unit)
         is_to_energy = self._is_energy(to_unit)
-        is_from_mass = self._is_mass(from_unit)
-        is_to_mass = self._is_mass(to_unit)
-        is_from_volume = self._is_volume(from_unit)
-        is_to_volume = self._is_volume(to_unit)
-
-        # Energy conversions
-        if is_from_energy or is_to_energy:
-            if not commodity:
-                raise ValueError("Commodity required for energy conversion")
-            comm = self.get_commodity(commodity)
-            if not comm.energy_content:
-                raise ValueError(f"No energy content defined for {commodity}")
-
-            ec = comm.energy_content.to("J/m^3")
-
-            if is_from_energy:
-                energy_J = qty.to("J")
-                # Energy -> Volume or Mass
-                volume_m3 = (energy_J / ec).to("m^3")
-                if is_to_volume:
-                    return volume_m3.to(to_unit).magnitude
-                elif is_to_mass:
-                    if comm.density is None:
-                        raise ValueError(
-                            f"Mass<->volume conversion not supported for {commodity!r} "
-                            f"(no density defined); cannot convert energy to mass"
-                        )
-                    density_kg_m3 = comm.density.to("kg/m^3")
-                    mass_kg = (volume_m3 * density_kg_m3).to("kg")
-                    return mass_kg.to(to_unit).magnitude
-                else:
-                    raise ValueError(f"Cannot convert energy to {to_unit}")
-            else:
-                # Volume/Mass -> Energy
-                if is_from_mass:
-                    if comm.density is None:
-                        raise ValueError(
-                            f"Mass<->volume conversion not supported for {commodity!r} "
-                            f"(no density defined); cannot convert mass to energy"
-                        )
-                    density_kg_m3 = comm.density.to("kg/m^3")
-                    mass_kg = qty.to("kg")
-                    volume_m3 = (mass_kg / density_kg_m3).to("m^3")
-                elif is_from_volume:
-                    volume_m3 = qty.to("m^3")
-                else:
-                    raise ValueError(f"Cannot convert {from_unit} to energy")
-                energy_J = (volume_m3 * ec).to("J")
-                return energy_J.to(to_unit).magnitude
+        involves_energy = is_from_energy or is_to_energy
 
-        # Mass <-> Volume conversions require density
-        if (is_from_mass and is_to_volume) or (is_from_volume and is_to_mass):
-            if not commodity:
+        if not commodity:
+            if involves_energy:
+                raise ValueError("Commodity required for energy conversion")
+            is_from_mass = self._is_mass(from_unit)
+            is_to_mass = self._is_mass(to_unit)
+            is_from_volume = self._is_volume(from_unit)
+            is_to_volume = self._is_volume(to_unit)
+            if (is_from_mass and is_to_volume) or (is_from_volume and is_to_mass):
                 raise ValueError(f"Commodity required for {from_unit} to {to_unit}")
-            comm = self.get_commodity(commodity)
-            if comm.density is None:
+            raise ValueError(
+                f"Cannot convert from {from_unit} to {to_unit} - incompatible dimensions"
+            )
+
+        # Let the commodity's context find the conversion path (including
+        # mass<->energy chaining). A missing property leaves no path -> pint
+        # raises DimensionalityError, which we translate to the domain error.
+        comm = self.get_commodity(commodity)
+        ctx = self._commodity_context(commodity)
+        try:
+            return qty.to(to_unit, ctx).magnitude
+        except DimensionalityError as exc:
+            if involves_energy and comm.energy_content is None:
+                raise ValueError(f"No energy content defined for {commodity}") from exc
+            if comm.density is None and (
+                self._is_mass(from_unit) or self._is_mass(to_unit)
+            ):
                 raise ValueError(
                     f"Mass<->volume conversion not supported for {commodity!r} "
                     f"(no density defined)"
-                )
-            density_kg_L = comm.density.to("kg/L")
-            density_kg_m3 = comm.density.to("kg/m^3")
-            if is_from_mass and is_to_volume:
-                mass_kg = qty.to("kg")
-                volume_L = (mass_kg / density_kg_L).to("L")
-                return volume_L.to(to_unit).magnitude
-            else:
-                volume_L = qty.to("L")
-                mass_kg = (volume_L * density_kg_L).to("kg")
-                return mass_kg.to(to_unit).magnitude
-
-        raise ValueError(
-            f"Cannot convert from {from_unit} to {to_unit} - incompatible dimensions"
-        )
+                ) from exc
+            raise ValueError(
+                f"Cannot convert from {from_unit} to {to_unit} - incompatible dimensions"
+            ) from exc
 
     def _convert_series(
         self,
@@ -450,25 +542,13 @@ class CommodityConverter:
         return from_per_day / to_per_day
 
     def _is_energy(self, unit: str) -> bool:
-        try:
-            (1 * self.ureg(unit)).to("J")
-            return True
-        except DimensionalityError:
-            return False
+        return self.ureg(unit).check("[energy]")
 
     def _is_mass(self, unit: str) -> bool:
-        try:
-            (1 * self.ureg(unit)).to("kg")
-            return True
-        except DimensionalityError:
-            return False
+        return self.ureg(unit).check("[mass]")
 
     def _is_volume(self, unit: str) -> bool:
-        try:
-            (1 * self.ureg(unit)).to("m^3")
-            return True
-        except DimensionalityError:
-            return False
+        return self.ureg(unit).check("[length]**3")
 
     @property
     def available_commodities(self) -> list:
@@ -629,12 +709,11 @@ def convert_price(
             f"convert_price currently only supports USD/* as target; got '{to_unit}'"
         )
 
-    # Unit-leg conversion (no FX yet — uses commodity factors)
+    # Unit-leg conversion (no FX yet — uses commodity factors).
+    # convfactor returns a nonzero float or raises, so no None/zero guard is
+    # needed here.
     factor = convfactor(from_bare_unit, to_bare_unit, commodity)
-    if factor is None or factor == 0:
-        unit_converted = value
-    else:
-        unit_converted = value / factor
+    unit_converted = value / factor
 
     # Same-base fractional case: USc -> USD, GBp -> GBP, EUc -> EUR, JPy -> JPY.
     # This is a pure /100 scale (or *100 in the reverse direction) — no FX

commodutil-4.4.0/commodutil/dates.py

@@ -0,0 +1,104 @@
+import datetime
+import re
+from datetime import datetime, date, time, timedelta
+
+from dateutil.relativedelta import relativedelta
+
+
+def _curmon():
+    return datetime.now().month
+
+
+def _curyear():
+    return datetime.now().year
+
+
+def _curmonyear():
+    return datetime(_curyear(), _curmon(), 1)
+
+
+def _curmonyear_str():
+    return "%s-%s" % (_curyear(), _curmon())  # get pandas time filtering
+
+
+def _last_day_of_prev_month():
+    return date.today().replace(day=1) - relativedelta(days=1)
+
+
+def _start_day_of_prev_month():
+    return date.today().replace(day=1) - relativedelta(months=1)
+
+
+def _prevmon():
+    return _start_day_of_prev_month().month
+
+
+def _prevmon_str():
+    sdpm = _start_day_of_prev_month()
+    return "%s-%s" % (sdpm.year, sdpm.month)  # get pandas time filtering
+
+
+def _nextyear():
+    return _curyear() + 1
+
+
+def _prevyear():
+    return _curyear() - 1
+
+
+# Compute "current date" values live on each attribute access (PEP 562) so that a
+# long-running process (Prefect worker, Dash app) that imports this module once still
+# sees the correct month/year after a boundary, instead of a stale import-time snapshot.
+_DYNAMIC = {
+    "curmon": _curmon,
+    "curyear": _curyear,
+    "curmonyear": _curmonyear,
+    "curmonyear_str": _curmonyear_str,
+    "last_day_of_prev_month": _last_day_of_prev_month,
+    "start_day_of_prev_month": _start_day_of_prev_month,
+    "prevmon": _prevmon,
+    "prevmon_str": _prevmon_str,
+    "nextyear": _nextyear,
+    "prevyear": _prevyear,
+}
+
+
+def __getattr__(name):
+    try:
+        return _DYNAMIC[name]()
+    except KeyError:
+        raise AttributeError(name)
+
+
+def find_year(df, use_delta=False):
+    """
+    Given a dataframe find the years in the column headings. Return a dict of colname to year
+    eg { 'Q1 2016' : 2016, 'Q1 2017' : 2017
+    """
+    res = {}
+    for colname in df:
+        colregex = re.findall("\d\d\d\d", str(colname))
+        colyear = None
+        if len(colregex) >= 1:
+            colyear = int(colregex[0])
+
+        if colyear:
+            res[colname] = colyear
+            if colyear and use_delta:
+                delta = colyear - _curyear()
+                res[colname] = delta
+        else:
+            res[colname] = colname
+
+    return res
+
+
+def time_until_end_of_day(dt=None):
+    # type: (datetime.datetime) -> datetime.timedelta
+    """
+    Get timedelta until end of day on the datetime passed, or current time.
+    """
+    if dt is None:
+        dt = datetime.now()
+    tomorrow = dt + timedelta(days=1)
+    return (datetime.combine(tomorrow, time.min) - dt).seconds

{commodutil-4.3.2 → commodutil-4.4.0}/commodutil/pandasutil.py

@@ -1,7 +1,6 @@
 import re
 from functools import reduce
 
-import numpy as np
 import pandas as pd
 
 
@@ -38,15 +37,11 @@ def fillna_downbet(df):
     """
     Fill weekends/holidays in timeseries but don't extend values beyond the last non-NaN entry.
     """
-    df = df.copy()
-    for col in df.columns:
-        # Drop all NaNs at once, vectorized and fast
-        non_nans = df[col].dropna()
-        if len(non_nans) > 1:
-            start, end = non_nans.index[0], non_nans.index[-1]
-            # Perform ffill only on the portion that has data
-            df.loc[start:end, col] = df.loc[start:end, col].ffill()
-    return df
+    # ffill(limit_area="inside") only fills gaps between existing valid values,
+    # never before the first or after the last non-NaN — equivalent to the old
+    # per-column ffill over [first_valid:last_valid]. Returns a new frame, so the
+    # input is not mutated. Requires pandas>=2.1.
+    return df.ffill(limit_area="inside")
 
 
 def sql_insert_statement_from_dataframe(df, table_name, print_statemnt=False):

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

@@ -33,6 +33,10 @@ from commodutil.standards.currency import (
     split_currency_unit,
     to_symbol,
 )
+from commodutil.standards.price_units import (
+    resolve_price_unit,
+    resolve_price_unit_from_attrs,
+)
 from commodutil.standards.regions import (
     CRUDE_GRADE_REGIONS,
     REGION_PATTERNS,
@@ -44,7 +48,9 @@ from commodutil.standards.regions import (
 )
 from commodutil.standards.units import (
     UNIT_MAP,
+    canonical_price_unit_token,
     canonical_quantity_unit,
+    canonical_unit_token,
     default_unit_for_commodity,
     quantity_unit_from_price_unit,
     to_pint_token,
@@ -75,6 +81,9 @@ __all__ = [
     "required_fx_pair",
     "split_currency_unit",
     "to_symbol",
+    # price_units
+    "resolve_price_unit",
+    "resolve_price_unit_from_attrs",
     # regions
     "CRUDE_GRADE_REGIONS",
     "REGION_PATTERNS",
@@ -85,7 +94,9 @@ __all__ = [
     "normalize_region",
     # units
     "UNIT_MAP",
+    "canonical_price_unit_token",
     "canonical_quantity_unit",
+    "canonical_unit_token",
     "default_unit_for_commodity",
     "quantity_unit_from_price_unit",
     "to_pint_token",

{commodutil-4.3.2 → commodutil-4.4.0}/commodutil/standards/commodities.py

@@ -61,6 +61,13 @@ COMMODITY_KEYWORDS = [
     ("Propane", "NGL", ["propane"]),
     ("NGL", "NGL", ["ngl"]),
     ("FFA", "Freight", ["freight", "ffa"]),
+    # Coal (API2 gross basis, added to COMMODITIES 2026-07). Group "Coal" is not
+    # in commodity_groups.COMMODITY_GROUPS (closed set mirroring the legacy
+    # MetadataDB2 CHECK constraint) — that tuple is deliberately NOT extended.
+    # Gold's commodity_group column is free-form and already carries values
+    # outside the closed set (e.g. 'Emissions'); no live consumer validates
+    # groups (2026-07 census).
+    ("Coal", "Coal", ["api2", "api4", "coal"]),
 ]
 
 COMMODITY_CONVERSION_MAP = {
@@ -86,6 +93,9 @@ COMMODITY_CONVERSION_MAP = {
     "Propane": "propane",
     "NGL": "lpg",
     "Ethane": "ethane",
+    # Coal (API2 gross basis) added to COMMODITIES 2026-07; keywords entry above
+    # enables display-name inference ("API2 Rotterdam Coal Futures" -> Coal).
+    "Coal": "coal",
 }