commodutil 4.2.0__tar.gz → 4.3.0__tar.gz

{commodutil-4.2.0 → commodutil-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.2.0
+Version: 4.3.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.2.0 → commodutil-4.3.0}/commodutil/__init__.py

@@ -36,6 +36,9 @@ _LAZY_EXPORTS = {
     "fractional_to_major": "commodutil.standards.currency",
     "is_fractional_currency": "commodutil.standards.currency",
     "split_currency_unit": "commodutil.standards.currency",
+    # standards.units (stdlib-only -- cheap, no pint)
+    "canonical_quantity_unit": "commodutil.standards.units",
+    "quantity_unit_from_price_unit": "commodutil.standards.units",
     # dates
     "curmon": "commodutil.dates",
     "curmonyear": "commodutil.dates",

{commodutil-4.2.0 → commodutil-4.3.0}/commodutil/convfactors.py

@@ -11,6 +11,7 @@ from dataclasses import dataclass
 import pandas as pd
 from functools import lru_cache
 
+from commodutil.standards import currency as _currency
 from commodutil.standards.units import to_pint_token as _to_pint_token
 
 logger = logging.getLogger(__name__)
@@ -542,8 +543,6 @@ def convfactor(from_unit: str, to_unit: str, commodity: Optional[str] = None) ->
 # above) and reads currency vocabulary directly from _currency. Callers
 # wanting currency vocabulary should import from commodutil.standards.currency.
 
-from commodutil.standards import currency as _currency
-
 
 def convert_price(
     value: Union[float, pd.Series],

{commodutil-4.2.0 → commodutil-4.3.0}/commodutil/standards/__init__.py

@@ -43,7 +43,9 @@ from commodutil.standards.regions import (
 )
 from commodutil.standards.units import (
     UNIT_MAP,
+    canonical_quantity_unit,
     default_unit_for_commodity,
+    quantity_unit_from_price_unit,
     to_pint_token,
 )
 
@@ -81,6 +83,8 @@ __all__ = [
     "normalize_region",
     # units
     "UNIT_MAP",
+    "canonical_quantity_unit",
     "default_unit_for_commodity",
+    "quantity_unit_from_price_unit",
     "to_pint_token",
 ]

{commodutil-4.2.0 → commodutil-4.3.0}/commodutil/standards/units.py

@@ -26,6 +26,8 @@ from __future__ import annotations
 
 from typing import Optional
 
+from commodutil.standards.currency import split_currency_unit
+
 
 # ---- Alias -> canonical normalisation ----
 
@@ -45,6 +47,7 @@ UNIT_MAP = {
     "metric tons": "mt",
     "metric tonne": "mt",
     "metric tonnes": "mt",
+    "mt": "mt",
     "tonne": "mt",
     "tonnes": "mt",
 }
@@ -72,6 +75,43 @@ def default_unit_for_commodity(commodity: Optional[str]) -> str:
     return _DEFAULT_UNIT.get(str(commodity).lower(), "bbl")
 
 
+def canonical_quantity_unit(unit: object) -> str | None:
+    """Return the canonical quantity unit token for free-form unit text.
+
+    This intentionally covers quoted physical units only: ``bbl``, ``gal``,
+    and ``mt``. Rate periods and currencies are outside this vocabulary.
+    """
+    if unit is None:
+        return None
+    text = str(unit).strip().lower()
+    if not text:
+        return None
+    return UNIT_MAP.get(text)
+
+
+def quantity_unit_from_price_unit(price_unit: object) -> str | None:
+    """Return the denominator quantity unit from a price-unit string.
+
+    Examples:
+        ``USD/MT`` -> ``mt``
+        ``USc/GAL`` -> ``gal``
+        ``$/BBL`` -> ``bbl``
+
+    Bare quantity units are also accepted. Bare rate units such as
+    ``bbl/day`` return ``None`` because the denominator is a time period, not
+    a physical quantity.
+    """
+    if price_unit is None:
+        return None
+    text = str(price_unit).strip()
+    if not text:
+        return None
+    _, unit_text = split_currency_unit(text)
+    if "/" in unit_text:
+        _, _, unit_text = text.partition("/")
+    return canonical_quantity_unit(unit_text)
+
+
 # ---- Pint-token normalisation ----
 
 
@@ -122,4 +162,10 @@ def to_pint_token(unit: Optional[str]) -> Optional[str]:
     return u
 
 
-__all__ = ["UNIT_MAP", "default_unit_for_commodity", "to_pint_token"]
+__all__ = [
+    "UNIT_MAP",
+    "canonical_quantity_unit",
+    "default_unit_for_commodity",
+    "quantity_unit_from_price_unit",
+    "to_pint_token",
+]

{commodutil-4.2.0 → commodutil-4.3.0}/commodutil.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.2.0
+Version: 4.3.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.2.0 → commodutil-4.3.0}/tests/test_standards_units.py

@@ -1,6 +1,10 @@
 """Tests for commodutil.standards.units."""
 
-from commodutil.standards.units import default_unit_for_commodity
+from commodutil.standards.units import (
+    canonical_quantity_unit,
+    default_unit_for_commodity,
+    quantity_unit_from_price_unit,
+)
 
 
 def test_natgas_defaults_to_mmbtu():
@@ -69,6 +73,25 @@ def test_unit_map_canonical_set_only_three():
     assert set(UNIT_MAP.values()) == {"bbl", "gal", "mt"}
 
 
+def test_canonical_quantity_unit_normalizes_common_labels():
+    assert canonical_quantity_unit("BBL") == "bbl"
+    assert canonical_quantity_unit("barrels") == "bbl"
+    assert canonical_quantity_unit("GAL") == "gal"
+    assert canonical_quantity_unit("Metric Tonnes") == "mt"
+    assert canonical_quantity_unit("mmbtu") is None
+    assert canonical_quantity_unit(None) is None
+
+
+def test_quantity_unit_from_price_unit_uses_quote_denominator():
+    assert quantity_unit_from_price_unit("USD/MT") == "mt"
+    assert quantity_unit_from_price_unit("usd/mt") == "mt"
+    assert quantity_unit_from_price_unit("USc/GAL") == "gal"
+    assert quantity_unit_from_price_unit("USC/GAL") == "gal"
+    assert quantity_unit_from_price_unit("$/BBL") == "bbl"
+    assert quantity_unit_from_price_unit("BBL") == "bbl"
+    assert quantity_unit_from_price_unit("bbl/day") is None
+
+
 # ---- to_pint_token tests ----