commodutil 5.4.0__tar.gz → 5.5.1__tar.gz

commodutil-5.5.1/.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.1/.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.1/.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.1/.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.4.0 → commodutil-5.5.1}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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`).

{commodutil-5.4.0 → commodutil-5.5.1}/PKG-INFO

@@ -1,17 +1,18 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 5.4.0
+Version: 5.5.1
 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.1/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-5.4.0 → commodutil-5.5.1}/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-5.4.0 → commodutil-5.5.1}/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):

{commodutil-5.4.0 → commodutil-5.5.1}/commodutil/dates.py

@@ -77,7 +77,7 @@ def find_year(df, use_delta=False):
     """
     res = {}
     for colname in df:
-        colregex = re.findall("\d\d\d\d", str(colname))
+        colregex = re.findall(r"\d\d\d\d", str(colname))
         colyear = None
         if len(colregex) >= 1:
             colyear = int(colregex[0])

{commodutil-5.4.0 → commodutil-5.5.1}/commodutil/forward/calendar.py

@@ -231,7 +231,7 @@ def half_year_contracts(contracts):
                 s.name = "Summer {}".format(year)
                 dfs.append(s)
 
-    res = pd.concat(dfs, axis=1)
+    res = pd.concat(dfs, axis=1, sort=True)
     # sort columns by years
     cols = list(res.columns)
     cols.sort(key=lambda s: s.split()[1])

{commodutil-5.4.0 → commodutil-5.5.1}/commodutil/forward/continuous.py

@@ -36,8 +36,8 @@ def generate_series(df, expiry_dates=None, roll_days=0, front_month=1, back_adju
     continuous_dfs = []
 
     for front_month_x in front_month:
-        mask_switch = pd.DataFrame(index=df.index, columns=df.columns)
-        mask_adjust = pd.DataFrame(index=df.index, columns=df.columns)
+        mask_switch = pd.DataFrame(index=df.index, columns=df.columns, dtype=float)
+        mask_adjust = pd.DataFrame(index=df.index, columns=df.columns, dtype=float)
 
         # Iterating over the columns (contracts)
         for contract in df.columns:
@@ -79,7 +79,9 @@ def generate_series(df, expiry_dates=None, roll_days=0, front_month=1, back_adju
 
         # Back-adjustment
         if back_adjust:
-            mask_adjust_series = mask_adjust.fillna(method='bfill').sum(axis=1, skipna=True, min_count=1).fillna(0)
+            mask_adjust_series = mask_adjust.bfill().sum(
+                axis=1, skipna=True, min_count=1
+            ).fillna(0)
             continuous_df = continuous_df.add(mask_adjust_series, axis=0)
 
         continuous_dfs.append(continuous_df)

{commodutil-5.4.0 → commodutil-5.5.1}/commodutil/forward/quarterly.py

@@ -100,7 +100,7 @@ def quarterly_contracts(contracts, col_format=None):
                 dfs.append(s)
 
     if len(dfs) > 0:
-        res = pd.concat(dfs, axis=1)
+        res = pd.concat(dfs, axis=1, sort=True)
         # sort columns by years
         cols = list(res.columns)
         cols.sort(key=lambda s: s.split()[1])

{commodutil-5.4.0 → commodutil-5.5.1}/commodutil/forward/spreads.py

@@ -1,4 +1,3 @@
-import datetime
 from calendar import month_abbr
 
 import pandas as pd
@@ -121,7 +120,7 @@ def all_monthly_spreads_extended(contracts, col_format=None):
     if not dfs:
         return None
 
-    res = pd.concat(dfs, axis=1)
+    res = pd.concat(dfs, axis=1, sort=True)
     legmap = {}
     for df in dfs:
         legmap.update(df.attrs)

{commodutil-5.4.0 → commodutil-5.5.1}/commodutil/forward/util.py

@@ -14,7 +14,7 @@ def convert_contract_to_date(contract):
     :param contract:
     :return:
     """
-    c = re.findall("\d\d\d\d\w", contract)
+    c = re.findall(r"\d\d\d\d\w", contract)
     if len(c) > 0:
         c = c[0]
     d = "%s-%s-1" % (c[:4], futures_month_conv_inv.get(c[-1], 0))

{commodutil-5.4.0 → commodutil-5.5.1}/commodutil/forwards.py

@@ -88,7 +88,7 @@ def spread_combination_quarter(contracts, combination_type, verbose_columns=True
         contracts.attrs = {}
     if combination_type.startswith("q"):
         q_contracts = quarterly_contracts(contracts)
-        m = re.search("q\dq\dq\d", combination_type)
+        m = re.search(r"q\dq\dq\d", combination_type)
         if m:
             q_spreads = fly_quarterly(
                 q_contracts,
@@ -104,7 +104,7 @@ def spread_combination_quarter(contracts, combination_type, verbose_columns=True
             if exclude_price_month:
                 contracts = q_spreads.apply(replace_last_month_with_nan, axis=0)
             return q_spreads
-        m = re.search("q\dq\d", combination_type)
+        m = re.search(r"q\dq\d", combination_type)
         if m:
             q_spreads = time_spreads_quarterly(
                 contracts, combination_type[0:2], combination_type[2:4]
@@ -121,7 +121,7 @@ def spread_combination_quarter(contracts, combination_type, verbose_columns=True
                 contracts = q_spreads.apply(replace_last_month_with_nan, axis=0)
             return q_spreads
 
-        m = re.search("q\d", combination_type)
+        m = re.search(r"q\d", combination_type)
         if m:
             q_contracts = q_contracts[
                 [

{commodutil-5.4.0 → commodutil-5.5.1}/commodutil/standards/__init__.py

@@ -1,7 +1,7 @@
 """commodutil.standards: canonical vocabularies for commodity trading.
 
 Re-exports the public surface of each submodule so callers can write
-`from commodutil.standards import normalize_region` instead of reaching
+`from commodutil.standards import normalize_trading_hub` instead of reaching
 into the submodule directly.
 """
 
@@ -34,19 +34,33 @@ from commodutil.standards.currency import (
     split_currency_unit,
     to_symbol,
 )
+from commodutil.standards.geography import (
+    COUNTRY_ALIASES,
+    COUNTRY_GROUP_MEMBERS,
+    COUNTRY_GROUP_ROWS,
+    COUNTRY_NAME_MAP,
+    VALID_COUNTRY_CODES,
+    VALID_COUNTRY_GROUP_KEYS,
+    CountryGroupRow,
+    canonical_country,
+    country_group_members,
+    country_in_group,
+    is_canonical_country,
+    is_canonical_country_group,
+)
 from commodutil.standards.price_unit import (
     PriceUnit,
     resolve_price_unit,
     resolve_price_unit_from_attrs,
 )
-from commodutil.standards.regions import (
+from commodutil.standards.trading_hubs import (
     CRUDE_GRADE_REGIONS,
-    REGION_PATTERNS,
+    TRADING_HUB_PATTERNS,
     VALID_CRUDE_GRADE_REGIONS,
-    VALID_REGIONS,
+    VALID_TRADING_HUBS,
     is_crude_grade_region,
-    is_valid_region,
-    normalize_region,
+    is_valid_trading_hub,
+    normalize_trading_hub,
 )
 from commodutil.standards.units import (
     UNIT_MAP,
@@ -85,18 +99,31 @@ __all__ = [
     "required_fx_pair",
     "split_currency_unit",
     "to_symbol",
+    # geography
+    "COUNTRY_ALIASES",
+    "VALID_COUNTRY_CODES",
+    "COUNTRY_NAME_MAP",
+    "canonical_country",
+    "is_canonical_country",
+    "CountryGroupRow",
+    "COUNTRY_GROUP_ROWS",
+    "VALID_COUNTRY_GROUP_KEYS",
+    "COUNTRY_GROUP_MEMBERS",
+    "is_canonical_country_group",
+    "country_group_members",
+    "country_in_group",
     # price_unit
     "PriceUnit",
     "resolve_price_unit",
     "resolve_price_unit_from_attrs",
-    # regions
+    # trading_hubs
     "CRUDE_GRADE_REGIONS",
-    "REGION_PATTERNS",
+    "TRADING_HUB_PATTERNS",
     "VALID_CRUDE_GRADE_REGIONS",
-    "VALID_REGIONS",
+    "VALID_TRADING_HUBS",
     "is_crude_grade_region",
-    "is_valid_region",
-    "normalize_region",
+    "is_valid_trading_hub",
+    "normalize_trading_hub",
     # units
     "UNIT_MAP",
     "canonical_price_unit_token",