commodutil 4.2.0__tar.gz → 4.3.2__tar.gz

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

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

@@ -35,7 +35,11 @@ _LAZY_EXPORTS = {
     "VALID_CURRENCY_TOKENS": "commodutil.standards.currency",
     "fractional_to_major": "commodutil.standards.currency",
     "is_fractional_currency": "commodutil.standards.currency",
+    "normalize_currency_token": "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.2}/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.2}/commodutil/standards/__init__.py

@@ -28,6 +28,7 @@ from commodutil.standards.currency import (
     VALID_CURRENCY_TOKENS,
     fractional_to_major,
     is_fractional_currency,
+    normalize_currency_token,
     required_fx_pair,
     split_currency_unit,
     to_symbol,
@@ -43,7 +44,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,
 )
 
@@ -68,6 +71,7 @@ __all__ = [
     "VALID_CURRENCY_TOKENS",
     "fractional_to_major",
     "is_fractional_currency",
+    "normalize_currency_token",
     "required_fx_pair",
     "split_currency_unit",
     "to_symbol",
@@ -81,6 +85,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.2}/commodutil/standards/currency.py

@@ -80,12 +80,56 @@ _VALID_CURRENCY_TOKENS = {
     "$",
 }
 
+_CURRENCY_TOKEN_LOOKUP = {token.upper(): token for token in _VALID_CURRENCY_TOKENS}
+_CURRENCY_TOKEN_ALIASES = {
+    "USC": "USc",
+    "US CENTS": "USc",
+    "U S CENTS": "USc",
+    "GBX": "GBp",
+    "GBPENCE": "GBp",
+    "GB PENCE": "GBp",
+    "PENCE": "GBp",
+    "RMB": "CNY",
+}
+
 # Public aliases — these are the import names downstream code should use.
 VALID_CURRENCY_TOKENS = _VALID_CURRENCY_TOKENS
 FRACTIONAL_TO_MAJOR = _FRACTIONAL_TO_MAJOR
 FRACTIONAL_CURRENCY_DIVISORS = _FRACTIONAL_CURRENCY_DIVISORS
 
 
+def _normalized_currency_lookup_key(token: str) -> str:
+    return " ".join(str(token).replace(".", " ").strip().upper().split())
+
+
+def normalize_currency_token(token: Optional[str]) -> Optional[str]:
+    """Return the canonical commodutil currency token for common aliases.
+
+    The canonical tokens remain ``VALID_CURRENCY_TOKENS``. This helper accepts
+    mixed case and legacy/fractional aliases used in vendor specs, such as
+    ``USC``/``US cents`` -> ``USc`` and ``GBX``/``pence`` -> ``GBp``. Unknown
+    values return ``None`` so callers can distinguish currency-like tokens
+    from physical units.
+    """
+    if token is None:
+        return None
+    cleaned = str(token).strip()
+    if not cleaned:
+        return None
+    if cleaned in _VALID_CURRENCY_TOKENS:
+        return cleaned
+
+    lower = cleaned.lower()
+    mapped = CURRENCY_MAP.get(lower)
+    if mapped:
+        return mapped
+
+    lookup_key = _normalized_currency_lookup_key(cleaned)
+    return _CURRENCY_TOKEN_LOOKUP.get(lookup_key) or _CURRENCY_TOKEN_ALIASES.get(
+        lookup_key
+    )
+
+
 def is_fractional_currency(token: str) -> bool:
     """Return True if `token` is a recognised fractional currency
     (e.g. 'GBp', 'USc'). Useful for detecting pure-scale conversions that
@@ -240,6 +284,7 @@ __all__ = [
     "FRACTIONAL_TO_MAJOR",
     "FRACTIONAL_CURRENCY_DIVISORS",
     "CURRENCY_MAP",
+    "normalize_currency_token",
     "is_fractional_currency",
     "fractional_to_major",
     "split_currency_unit",

{commodutil-4.2.0 → commodutil-4.3.2}/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,8 +47,13 @@ UNIT_MAP = {
     "metric tons": "mt",
     "metric tonne": "mt",
     "metric tonnes": "mt",
+    "mt": "mt",
     "tonne": "mt",
     "tonnes": "mt",
+    "pound": "lb",
+    "pounds": "lb",
+    "lb": "lb",
+    "lbs": "lb",
 }
 
 
@@ -72,6 +79,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 ----
 
 
@@ -89,6 +133,7 @@ def to_pint_token(unit: Optional[str]) -> Optional[str]:
       / ``CUBIC_METER`` / ``m3`` (case-insensitive exact match) -> ``m^3``.
     - Rate forms: ``m3/...`` / ``M3/...`` -> ``m^3/...``.
     - Energy casing: ``BTU`` -> ``Btu``; ``MMBTU`` -> ``MMBtu``.
+    - Pound casing/plurals: ``LBS`` / ``lbs`` -> ``lb``.
 
     Other tokens pass through unchanged. Aliases like ``barrel``, ``tonne``,
     ``gallon`` are not handled here -- they are registered as pint aliases
@@ -119,7 +164,15 @@ def to_pint_token(unit: Optional[str]) -> Optional[str]:
         u = "Btu"
     if u == "MMBTU":
         u = "MMBtu"
+    if u.upper() == "LBS":
+        u = "lb"
     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.2}/commodutil.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 4.2.0
+Version: 4.3.2
 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.2}/tests/test_price_conv.py

@@ -206,6 +206,11 @@ def test_bug2_usc_to_usd_no_fx_required():
     assert out == pytest.approx(0.005, rel=1e-9)
 
 
+def test_usc_per_pound_to_usd_per_pound_no_fx_required():
+    out = convfactors.convert_price(71.26, "USc/LBS", "USD/lb")
+    assert out == pytest.approx(0.7126, rel=1e-9)
+
+
 def test_bug2_gbp_pence_to_gbp_no_fx_required():
     """Bug 2: GBp -> GBP is a pure /100 scale (no FX)."""
     out = convfactors.convert_price(50.0, "GBp/therm", "GBP/therm")

{commodutil-4.2.0 → commodutil-4.3.2}/tests/test_standards_currency.py

@@ -7,6 +7,7 @@ from commodutil.standards.currency import (
     VALID_CURRENCY_TOKENS,
     fractional_to_major,
     is_fractional_currency,
+    normalize_currency_token,
     required_fx_pair,
     split_currency_unit,
     to_symbol,
@@ -40,6 +41,21 @@ def test_fractional_to_major():
     assert fractional_to_major("") == ""
 
 
+def test_normalize_currency_token():
+    assert normalize_currency_token("USD") == "USD"
+    assert normalize_currency_token("usd") == "USD"
+    assert normalize_currency_token("$") == "$"
+    assert normalize_currency_token("USC") == "USc"
+    assert normalize_currency_token("U.S. cents") == "USc"
+    assert normalize_currency_token("GBX") == "GBp"
+    assert normalize_currency_token("pence") == "GBp"
+    assert normalize_currency_token("RMB") == "CNY"
+    assert normalize_currency_token("us dollars and cents") == "USD"
+    assert normalize_currency_token("bbl") is None
+    assert normalize_currency_token("") is None
+    assert normalize_currency_token(None) is None
+
+
 def test_fractional_currency_cac_auc_correctly_routed():
     # Regression guard for the pre-2026-05-14 bug where CAc/AUc were valid
     # currency tokens but had no fractional rule, so required_fx_pair
@@ -155,6 +171,7 @@ def test_legacy_convfactors_currency_shims_are_gone():
         "FRACTIONAL_TO_MAJOR",
         "fractional_to_major",
         "is_fractional_currency",
+        "normalize_currency_token",
         "split_currency_unit",
         "_split_currency_unit",
         "_FRACTIONAL_CURRENCY_DIVISORS",

{commodutil-4.2.0 → commodutil-4.3.2}/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():
@@ -62,11 +66,39 @@ def test_unit_map_metric_ton_variants():
     assert UNIT_MAP["tonnes"] == "mt"
 
 
-def test_unit_map_canonical_set_only_three():
-    """UNIT_MAP normalises to exactly the canonical units bbl / gal / mt."""
+def test_unit_map_pound_variants():
     from commodutil.standards.units import UNIT_MAP
 
-    assert set(UNIT_MAP.values()) == {"bbl", "gal", "mt"}
+    assert UNIT_MAP["pound"] == "lb"
+    assert UNIT_MAP["pounds"] == "lb"
+    assert UNIT_MAP["lb"] == "lb"
+    assert UNIT_MAP["lbs"] == "lb"
+
+
+def test_unit_map_canonical_set():
+    """UNIT_MAP normalises to the canonical physical quote units."""
+    from commodutil.standards.units import UNIT_MAP
+
+    assert set(UNIT_MAP.values()) == {"bbl", "gal", "mt", "lb"}
+
+
+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 ----
@@ -97,6 +129,13 @@ def test_to_pint_token_energy_casing():
     assert to_pint_token("MMBTU") == "MMBtu"
 
 
+def test_to_pint_token_pound_casing():
+    from commodutil.standards.units import to_pint_token
+
+    assert to_pint_token("LBS") == "lb"
+    assert to_pint_token("lbs") == "lb"
+
+
 def test_to_pint_token_whitespace_stripped():
     from commodutil.standards.units import to_pint_token