worldbank-commodities 0.5.0__tar.gz

worldbank_commodities-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Ruff lint
+        run: uv run ruff check --output-format=github .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Codespell
+        run: uv run codespell src tests README.md CHANGELOG.md
+
+      - name: Deptry
+        run: uv run deptry src
+
+      - name: Docstring coverage (interrogate)
+        run: uv run interrogate -c pyproject.toml src tests
+
+      - name: Type check (mypy)
+        run: uv run mypy
+
+      - name: Tests
+        run: uv run pytest --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          fail_ci_if_error: false

worldbank_commodities-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write # required for PyPI Trusted Publishing (OIDC)
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

worldbank_commodities-0.5.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.env
+
+# Build artifacts
+dist/
+build/
+
+# Tooling caches / reports
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Local cache of downloaded World Bank workbooks
+.cache/
+*.xlsx
+*.xls
+
+# Extracted data outputs (re-downloadable via the wrapper)
+wb_commodities_*.csv
+wb_commodities_*.xlsx
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/

worldbank_commodities-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.1
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        additional_dependencies: ["tomli"]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.18.2
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pandas-stubs
+          - types-openpyxl
+          - types-requests

worldbank_commodities-0.5.0/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com),
+and this project adheres to [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-08-01
+
+### Added
+
+- Wide output now includes a leading `mdates` column (monthly frequency only),
+  so wide CSV/Excel extracts also carry the Stata monthly id
+  ([#11](https://github.com/hmorao95/worldbank-commodities/issues/11)).
+
+## [0.4.1] - 2026-08-01
+
+### Fixed
+
+- `mdates` is now added only for the monthly frequency. On annual data it was a
+  misleading `<year>m1` for every row; annual output omits the column
+  ([#9](https://github.com/hmorao95/worldbank-commodities/issues/9)).
+- CLI `get-prices --out` routes by file extension, so `--out data.xlsx` writes a
+  real Excel workbook instead of CSV content under an `.xlsx` name
+  ([#9](https://github.com/hmorao95/worldbank-commodities/issues/9)).
+
+## [0.4.0] - 2026-08-01
+
+### Added
+
+- Long output now includes an `mdates` column, a Stata-style monthly id such as
+  `1960m1` (lowercase `m`, no zero-padding), for merging with Stata series
+  ([#7](https://github.com/hmorao95/worldbank-commodities/issues/7)).
+
+### Fixed
+
+- `to_excel` writes dates without a time component, so Excel shows `1960-01-01`
+  rather than `1960-01-01 00:00:00`
+  ([#7](https://github.com/hmorao95/worldbank-commodities/issues/7)).
+
+## [0.3.0] - 2026-08-01
+
+### Added
+
+- `to_excel()` and the CLI `to-excel` subcommand write prices to an Excel
+  (`.xlsx`) workbook, mirroring `to_csv`
+  ([#3](https://github.com/hmorao95/worldbank-commodities/issues/3)).
+
+## [0.2.1] - 2026-08-01
+
+### Fixed
+
+- `get_prices` now accepts a single commodity name as a plain string. Previously
+  a string filter was iterated character-by-character and matched essentially
+  every commodity; a non-matching string now raises `ValueError` as expected
+  ([#1](https://github.com/hmorao95/worldbank-commodities/issues/1)).
+- The CLI prints a concise `Error: ...` line and exits 1 for expected errors
+  (unknown commodity or frequency, changed page layout, malformed CSV) instead
+  of dumping a full Python traceback.
+
+## [0.2.0] - 2026-08-01
+
+### Changed
+
+- The command-line interface is now generated from the library with
+  [python-fire](https://github.com/google/python-fire): each operation is a
+  subcommand (`list-commodities`, `get-prices`, `to-csv`, `update-csv`,
+  `new-observations`) with flags derived from the method signatures, replacing
+  the hand-written argparse flags. **Breaking**: `--list`, `--out`, `--update`
+  and the other old flags are gone; see the README for the new syntax.
+
+### Fixed
+
+- Removed the fixed mypy `python_version = "3.10"` so recent numpy/pandas stubs
+  that use PEP 695 `type` syntax type-check on Python 3.12+.
+
+### Documentation
+
+- Rewrote module, class, method and inline docstrings/comments in a fuller,
+  fully-explained style (typed Args/Returns/Raises and per-step commentary).
+
+## [0.1.0] - 2026-08-01
+
+### Added
+
+- `WorldBankCommodities` client for the World Bank "Pink Sheet" (Commodity
+  Markets) price data, with automatic discovery of the current monthly/annual
+  workbook URLs (which carry a monthly-changing hash).
+- `get_prices()` — tidy long or wide DataFrames, with case-insensitive
+  substring filtering by commodity and inclusive `start`/`end` date bounds.
+- `list_commodities()` — catalog of the 71 available series and their units.
+- `to_csv()` — one-liner extract to a CSV file.
+- `update_csv()` — incremental updates that upsert on `(commodity, date)`,
+  appending new observations and overwriting values the World Bank later
+  revises.
+- `new_observations()` — file-free incremental helper: given an already-extracted
+  long DataFrame (or long-CSV path), returns only the rows you are missing
+  (newer dates and never-seen commodities), with an `include_revisions` toggle.
+  It is the shared building block behind `update_csv()`.
+- `examples/incremental.py` — runnable, inline-commented walkthrough of the
+  incremental extraction scenarios.
+- On-disk caching of the downloaded workbooks (24 h TTL) plus in-process
+  memoisation.
+- Command-line interface (`worldbank-commodities` / `python -m
+  worldbank_commodities`) with `--list`, `--freq`, `--commodity`, `--start`,
+  `--end`, `--wide`, `--out`, `--update` and `--no-cache`.
+- `src/` package layout, `py.typed` marker, and a network-mocked pytest suite
+  (38 tests, 96% coverage).
+- Tooling: uv project config, strict ruff lint/format, mypy `--strict`,
+  deptry, interrogate (docstring coverage), codespell, pre-commit hooks, and a
+  GitHub Actions CI workflow.
+
+### Fixed
+
+- `update_csv` now detects and applies World Bank **revisions** to
+  already-stored months instead of only appending strictly-newer rows.
+- `get_prices(wide=True)` uses `pivot` so a duplicate `(date, commodity)` key
+  raises loudly instead of being silently averaged.
+- `discover_urls` selects workbook links deterministically (prefers the
+  `Historical` workbook) rather than relying on set iteration order.
+- `update_csv` validates that the target file is in the long format and raises
+  a clear error for wide CSVs.
+
+[Unreleased]: https://github.com/hmorao95/worldbank-commodities/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/hmorao95/worldbank-commodities/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/hmorao95/worldbank-commodities/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/hmorao95/worldbank-commodities/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/hmorao95/worldbank-commodities/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/hmorao95/worldbank-commodities/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/hmorao95/worldbank-commodities/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/hmorao95/worldbank-commodities/releases/tag/v0.1.0

worldbank_commodities-0.5.0/CITATION.cff

@@ -0,0 +1,32 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using these metadata."
+title: "worldbank-commodities"
+abstract: >-
+  A small Python wrapper to extract World Bank "Pink Sheet" (Commodity Markets)
+  commodity price data — crude oil, natural gas, coal, metals, fertilizers and
+  agricultural products — as tidy pandas DataFrames.
+type: software
+authors:
+  - family-names: "Morão"
+    given-names: "Hugo"
+    email: "hfmorao@gmail.com"
+version: "0.5.0"
+date-released: "2026-08-01"
+license: MIT
+repository-code: "https://github.com/hmorao95/worldbank-commodities"
+url: "https://github.com/hmorao95/worldbank-commodities"
+keywords:
+  - world-bank
+  - commodities
+  - pink-sheet
+  - prices
+  - energy
+  - oil
+  - python
+references:
+  - type: data
+    title: "World Bank Commodity Price Data (The Pink Sheet)"
+    authors:
+      - name: "The World Bank"
+    url: "https://www.worldbank.org/en/research/commodity-markets"
+    notes: "Underlying commodity price data, licensed CC BY 4.0."

worldbank_commodities-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo Morão
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.