commodutil 4.7.0__tar.gz → 5.5.0__tar.gz

commodutil-5.5.0/.github/workflows/1_tests.yml

@@ -0,0 +1,40 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ['3.11', '3.12']
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out code repository
+        uses: actions/checkout@v7.0.0
+
+      - name: Set up uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          version: '0.11.28'
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      # Oil_Feed is private and GitHub has no OIL_FEED_PAT secret yet. Resolve
+      # from public PyPI without changing the committed Azure lock.
+      - name: Resolve project test dependencies from public PyPI
+        run: |
+          python -c "from pathlib import Path; Path('uv.lock').unlink()"
+          uv --no-config sync --default-index https://pypi.org/simple --no-default-groups --group test
+
+      - name: Run unit tests
+        run: uv run --no-sync pytest

commodutil-5.5.0/.github/workflows/2_coverage.yml

@@ -0,0 +1,51 @@
+name: Code coverage
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    env:
+      OS: ubuntu-latest
+      PYTHON: '3.12'
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out code repository
+        uses: actions/checkout@v7.0.0
+
+      - name: Set up uv and Python 3.12
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          version: '0.11.28'
+          python-version: '3.12'
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      # Oil_Feed is private and GitHub has no OIL_FEED_PAT secret yet. Resolve
+      # from public PyPI without changing the committed Azure lock.
+      - name: Resolve project test dependencies from public PyPI
+        run: |
+          python -c "from pathlib import Path; Path('uv.lock').unlink()"
+          uv --no-config sync --default-index https://pypi.org/simple --no-default-groups --group test
+
+      - name: Generate coverage report
+        run: |
+          uv run --no-sync coverage run -m pytest
+          uv run --no-sync coverage xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v7.0.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          env_vars: OS,PYTHON
+          fail_ci_if_error: true
+          files: coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          verbose: true

commodutil-5.5.0/.github/workflows/3_linting.yml

@@ -0,0 +1,49 @@
+name: Lint and format code
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      OS: ubuntu-latest
+      PYTHON: '3.12'
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out code repository
+        uses: actions/checkout@v7.0.0
+
+      - name: Set up uv and Python 3.12
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          version: '0.11.28'
+          python-version: '3.12'
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      # Oil_Feed is private and GitHub has no OIL_FEED_PAT secret yet. Resolve
+      # from public PyPI without changing the committed Azure lock.
+      - name: Resolve project development dependencies from public PyPI
+        run: |
+          python -c "from pathlib import Path; Path('uv.lock').unlink()"
+          uv --no-config sync --default-index https://pypi.org/simple --no-default-groups --group dev
+
+      - name: Lint with pylint
+        continue-on-error: true
+        run: uv run --no-sync pylint commodutil
+
+      - name: Run Black check
+        continue-on-error: true
+        run: uv run --no-sync black --check .
+
+      - name: Check type hints with mypy
+        continue-on-error: true
+        run: |
+          uv run --no-sync mypy commodutil
+          uv run --no-sync mypy tests

commodutil-5.5.0/.github/workflows/4_release.yml

@@ -0,0 +1,58 @@
+name: Upload release to PyPI
+
+on:
+  push:
+    tags:
+      - '*'
+  release:
+    types: [ created ]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      OS: ubuntu-latest
+      PYTHON: '3.12'
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out code repository
+        uses: actions/checkout@v7.0.0
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv and Python 3.12
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          version: '0.11.28'
+          python-version: '3.12'
+          enable-cache: true
+          cache-dependency-glob: pyproject.toml
+
+      - name: Get version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=$VERSION" >> "$GITHUB_ENV"
+          echo "Building version: $VERSION"
+
+      # Oil_Feed is private and GitHub has no OIL_FEED_PAT secret yet. Resolve
+      # from public PyPI without changing the committed Azure lock.
+      - name: Resolve release tooling from public PyPI
+        run: |
+          python -c "from pathlib import Path; Path('uv.lock').unlink()"
+          uv --no-config sync --default-index https://pypi.org/simple --no-default-groups --group release
+
+      - name: Build source and wheel distributions
+        run: uv --no-config build --no-sources
+
+      - name: Publish to TestPyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TESTPYPI_API_TOKEN }}
+        run: uv run --no-sync twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv run --no-sync twine upload dist/*

commodutil-5.5.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 5.5.0 - 2026-07-27
+
+- Added `commodutil.standards.geography` with pycountry-backed countries, desk aliases, and membership-defined country groups; added `pycountry` as a production dependency.
+- Breaking: `standards.regions` renamed to `standards.trading_hubs`; region-named symbols renamed (`REGION_PATTERNS` -> `TRADING_HUB_PATTERNS`, `VALID_REGIONS` -> `VALID_TRADING_HUBS`, `normalize_region` -> `normalize_trading_hub`, `is_valid_region` -> `is_valid_trading_hub`); no compatibility shim. Migrate imports to `commodutil.standards.trading_hubs`. `CRUDE_GRADE_REGIONS` family unchanged (relocated).
+
+## 5.4.1 - 2026-07-16
+
+- Added pandas 3 compatibility and removed project-owned deprecation and invalid-escape warnings.
+- Migrated Azure Pipelines and GitHub Actions to reproducible, locked uv project-mode installs.
+
+## 5.4.0 - 2026-07-12
+
+- Added `normalize_price_unit_strict` and `is_canonical_price_unit` to `commodutil.standards.units` (and the `commodutil` / `commodutil.standards` facades): the STRICT counterpart to the lenient `canonical_price_unit_token`. Where the lenient token preserves unrecognised currency/unit fragments so it can label any quote string, the strict variant returns a canonical `CCY/unit` token only when both legs resolve (recognised currency over a `canonical_quantity_unit` denominator) and `None` otherwise — for validating a curated price-unit qualifier that must round-trip through conversion (e.g. `usd_ton`/`USD/ton` refused, `USD/MT` -> `USD/mt`).
+
+## 5.0.1 - 2026-07-03
+
+- Breaking: removed `default_unit_for_commodity` and `_DEFAULT_UNIT` from `commodutil.standards.units`; these fabricated per-commodity quote units, and the gold instrument registry answers this per-instrument.
+- Breaking: removed the `commodutil.standards.price_units` module. Price-unit resolution (`resolve_price_unit`, `resolve_price_unit_from_attrs`) moved into `commodutil.standards.price_unit` alongside the `PriceUnit` value type. Migrate imports to `commodutil.standards.price_unit`.
+- First release of the 5.x line; the 5.0.0 version number is unusable on the feed.
+
+## 4.10.0 - 2026-07-03
+
+- Added exchange unit spellings for `MTONS`, `CBM`, `THM`, and `KL` to the unit registry, with `KL`/kilolitre spellings resolving to the canonical `m^3` unit.
+- Moved commodity alias ownership to `commodutil.standards.commodities.COMMODITY_ALIASES`; `CommodityConverter` now consumes a defensive copy from that source.
+- Breaking: removed the `commodutil.convfactors.ALIASES` re-export. Migrate callers to `from commodutil.standards.commodities import COMMODITY_ALIASES`.
+
+## 4.8.0 - 2026-07-03
+
+- Split price, currency, and FX conversion helpers into `commodutil.priceconv`, while keeping lazy compatibility exports from `commodutil.convfactors` for the price-conversion API.
+- Consolidated petrochemical taxonomy keywords into `commodutil.standards.commodities`.
+- Added `infer_ngl_species` for discrete NGL species inference from free text.
+
+## 4.7.0 - 2026-07-03
+
+- Fixed ethanol density to `0.7937 kg/L`, preserving the EIA gross per-volume energy content while correcting mass-based conversion factors.
+- Promoted `kg` and bare cubic-metre spellings (`m3`, `m^3`, `m**3`) into the `UNIT_MAP` tier so vendor-spec parsers can resolve them directly.
+
+## 4.6.0 - 2026-07-02
+
+- Replaced hand-rolled scalar rate-period conversion with `PriceUnit` parsing and Pint-derived period ratios, while preserving calendar-aware month/day handling for series.
+- Added `align_fx`, `ConversionResult`, and `convert_price_result` for explicit price-conversion results, currency-leg fallback, and keep-raw error handling.
+
+## 4.5.0 - 2026-07-02
+
+- Added the `PriceUnit` value type for structured price-unit parsing across currency, quantity-unit, and rate-period legs.
+- Added `commodutil.standards.unit_registry` as the single source of truth for unit vocabulary, public unit maps, and Pint definitions.
+- Added ICE unit spellings for `MMBtu`, `GJ`, `MWh`, `m^3`, `MW`, `RIN`, `FEU`, and `day`, covering the registry gap identified in ICE contract metadata.
+
+## 4.4.0 - 2026-07-02
+
+- Standardized covered liquid and biofuel energy-content factors on the EIA gross/HHV basis, documenting explicit exceptions and basis assumptions.
+- Added API2/coal support with mass-basis energy content for density-less solid-fuel conversions and Coal taxonomy inference.
+- Added the golden-factor regression fixture and validation tests for quantity, rate, and price conversions.

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

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

commodutil-5.5.0/README.md

@@ -0,0 +1,21 @@
+# commodutil
+Common commodity and oil analytics utilities.
+
+## Dependency modes
+`pyproject.toml` is commodutil's only dependency declaration. Runtime dependencies live in
+`project.dependencies`; PEP 735 groups provide `test`, `dev`, and `release` tooling.
+
+Azure Pipelines uses locked project mode. `uv.lock` fixes the exact Oil_Feed solution, and
+the pipeline installs the `test` group on Python 3.11 and 3.12 before testing the exact wheel
+built once upstream. After changing dependencies, regenerate the lock with uv 0.11.28 against
+Oil_Feed and run `uv lock --check`. The lock may contain the credential-free feed URL, but it
+must never contain usernames, tokens, or other registries.
+
+The shared pipeline template also supports a requirements mode for other legacy repositories.
+commodutil does not use that mode and intentionally has no `requirements*.txt` manifests.
+
+Oil_Feed is private and this GitHub repository currently has no feed credential. GitHub Actions
+therefore removes the feed-specific lock only in its ephemeral checkout and resolves the same
+pyproject groups from public PyPI. To make GitHub use the committed frozen solution, add an
+`OIL_FEED_PAT` repository secret with Azure Artifacts Packaging Read permission, then replace
+the public-resolution step with runtime-authenticated `uv sync --frozen`. Never commit the PAT.

{commodutil-4.7.0 → commodutil-5.5.0}/azure-build-pipelines.yml

@@ -9,14 +9,22 @@ extends:
   template: templates/python-packages-pipeline.yml@pipeline-templates
   parameters:
     packageName: 'commodutil'
+    pythonVersion: '3.12'
+    additionalPythonVersions:
+      - '3.11'
+    dependencyMode: project
+    dependencyGroups:
+      - test
+    installOdbc: false
     createRefinitivConfig: false
 
 pool: Self-Hosted-AWS
 
 trigger:
+  batch: true
   branches:
     include:
       - main
   tags:
     include:
-      - "*"
+      - "*"

{commodutil-4.7.0 → commodutil-5.5.0}/commodutil/__init__.py

@@ -7,7 +7,7 @@ facade eagerly imported convfactors and its pint registry).
 
 Cheap paths:
     import commodutil                                  # near-instant
-    from commodutil.standards.regions import ...       # stdlib only
+    from commodutil.standards.trading_hubs import ...  # stdlib only
     from commodutil.standards.currency import ...      # stdlib only
 
 Heavier paths (lazy-load their sub-module on first attribute access):
@@ -22,7 +22,6 @@ from __future__ import annotations
 # resolve via __getattr__ below.
 _LAZY_EXPORTS = {
     # convfactors (heaviest -- pint registry + Commodity dataclass init)
-    "ALIASES": "commodutil.convfactors",
     "COMMODITIES": "commodutil.convfactors",
     "Commodity": "commodutil.convfactors",
     "convert": "commodutil.convfactors",
@@ -41,6 +40,8 @@ _LAZY_EXPORTS = {
     "canonical_price_unit_token": "commodutil.standards.units",
     "canonical_quantity_unit": "commodutil.standards.units",
     "canonical_unit_token": "commodutil.standards.units",
+    "is_canonical_price_unit": "commodutil.standards.units",
+    "normalize_price_unit_strict": "commodutil.standards.units",
     "quantity_unit_from_price_unit": "commodutil.standards.units",
     # dates
     "curmon": "commodutil.dates",