hdx-python-country 4.1.2__tar.gz → 4.1.3__tar.gz

{hdx_python_country-4.1.2 → hdx_python_country-4.1.3}/.github/workflows/run-python-tests.yaml

@@ -25,7 +25,7 @@ jobs:
           python-version: "3.13"
 
       - name: Install dependencies
-        run: uv sync --frozen
+        run: uv sync --frozen --extra wfp
 
       - name: Check styling
         run: |
@@ -37,7 +37,7 @@ jobs:
 
       - name: Publish Unit Test Results
         uses: EnricoMi/publish-unit-test-result-action@v2
-        if: always()
+        if: success()
         with:
           files: test-results.xml
 

{hdx_python_country-4.1.2 → hdx_python_country-4.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hdx-python-country
-Version: 4.1.2
+Version: 4.1.3
 Summary: HDX Python country code and exchange rate (fx) utilities
 Project-URL: Homepage, https://github.com/OCHA-DAP/hdx-python-country
 Project-URL: Repository, https://github.com/OCHA-DAP/hdx-python-country
@@ -31,6 +31,8 @@ Requires-Dist: hdx-python-utilities<5,>=4.1.2
 Requires-Dist: tenacity
 Provides-Extra: docs
 Requires-Dist: mkapi; extra == 'docs'
+Provides-Extra: wfp
+Requires-Dist: data-bridges-client<10,>=9.0.0; extra == 'wfp'
 Description-Content-Type: text/markdown
 
 [![Build Status](https://github.com/OCHA-DAP/hdx-python-country/actions/workflows/run-python-tests.yaml/badge.svg)](https://github.com/OCHA-DAP/hdx-python-country/actions/workflows/run-python-tests.yaml)
@@ -140,3 +142,28 @@ To run the tests and view coverage, execute:
 The documentation, including API documentation, is generated using ReadtheDocs and
 MkDocs with Material. As you change the source code, remember to update the
 documentation at `documentation/index.md`.
+
+## WFP DataBridges Client
+
+The `WFPAPI` class (`hdx.location.wfp_api`) uses WFP's `data-bridges-client` library, which is
+published on WFP's own package index rather than PyPI. To install it, use the `wfp` extra with
+that index added:
+
+```shell
+    pip install "hdx-python-country[wfp]" \
+      --extra-index-url https://d2i4vvypvg40rv.cloudfront.net/pypi/ \
+      --index-strategy unsafe-best-match
+```
+
+If using `uv`, add the following to your project's `pyproject.toml`:
+
+```toml
+[tool.uv]
+index-strategy = "unsafe-best-match"
+
+[[tool.uv.index]]
+name = "wfp"
+url = "https://d2i4vvypvg40rv.cloudfront.net/pypi/"
+```
+
+then run `uv sync --extra wfp`.

{hdx_python_country-4.1.2 → hdx_python_country-4.1.3}/README.md

@@ -105,3 +105,28 @@ To run the tests and view coverage, execute:
 The documentation, including API documentation, is generated using ReadtheDocs and
 MkDocs with Material. As you change the source code, remember to update the
 documentation at `documentation/index.md`.
+
+## WFP DataBridges Client
+
+The `WFPAPI` class (`hdx.location.wfp_api`) uses WFP's `data-bridges-client` library, which is
+published on WFP's own package index rather than PyPI. To install it, use the `wfp` extra with
+that index added:
+
+```shell
+    pip install "hdx-python-country[wfp]" \
+      --extra-index-url https://d2i4vvypvg40rv.cloudfront.net/pypi/ \
+      --index-strategy unsafe-best-match
+```
+
+If using `uv`, add the following to your project's `pyproject.toml`:
+
+```toml
+[tool.uv]
+index-strategy = "unsafe-best-match"
+
+[[tool.uv.index]]
+name = "wfp"
+url = "https://d2i4vvypvg40rv.cloudfront.net/pypi/"
+```
+
+then run `uv sync --extra wfp`.

{hdx_python_country-4.1.2 → hdx_python_country-4.1.3}/pyproject.toml

@@ -42,6 +42,7 @@ dependencies = [
 
 [project.optional-dependencies]
 docs = ["mkapi"]
+wfp = ["data-bridges-client>=9.0.0,<10"]
 
 [dependency-groups]
 dev = [
@@ -49,6 +50,7 @@ dev = [
     "pytest-cov",
     "pre-commit",
     "ruff==0.14.13",
+    "data-bridges-client>=9.0.0,<10",
 ]
 
 [project.urls]
@@ -76,6 +78,17 @@ packages = ["src/hdx"]
 [tool.hatch.metadata]
 allow-direct-references = true
 
+# ----------------------------------------------------------------------------
+# uv (Package Management)
+# ----------------------------------------------------------------------------
+
+[tool.uv]
+index-strategy = "unsafe-best-match"
+
+[[tool.uv.index]]
+name = "wfp"
+url = "https://d2i4vvypvg40rv.cloudfront.net/pypi/"
+
 # ----------------------------------------------------------------------------
 # Ruff (Linting & Formatting)
 # ----------------------------------------------------------------------------

{hdx_python_country-4.1.2 → hdx_python_country-4.1.3}/src/hdx/location/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '4.1.2'
-__version_tuple__ = version_tuple = (4, 1, 2)
+__version__ = version = '4.1.3'
+__version_tuple__ = version_tuple = (4, 1, 3)
 
 __commit_id__ = commit_id = None

hdx_python_country-4.1.3/src/hdx/location/wfp_api.py

@@ -0,0 +1,323 @@
+import json
+import logging
+from collections.abc import Callable
+from datetime import date, datetime
+from os import getenv
+from typing import Any
+
+from data_bridges_client import (
+    ApiClient,
+    ApiException,
+    CommoditiesApi,
+    Configuration,
+    CurrencyApi,
+    MarketPricesApi,
+    MarketsApi,
+    PagedCommodityListDTO,
+    PagedCurrencyListDTO,
+    PagedMarketListDTO,
+    UsdIndirectQuotationPagedResult,
+    ViewExtendedMonthlyAggregatedPricePagedResult,
+)
+from data_bridges_client.models.commodity_dto import CommodityDTO
+from data_bridges_client.models.currency_dto import CurrencyDTO
+from data_bridges_client.models.market_dto import MarketDTO
+from data_bridges_client.models.usd_indirect_quotation import UsdIndirectQuotation
+from data_bridges_client.models.view_extended_monthly_aggregated_price import (
+    ViewExtendedMonthlyAggregatedPrice,
+)
+from data_bridges_client.token import WfpApiToken
+from hdx.utilities.loader import load_json
+from hdx.utilities.retriever import Retrieve
+from tenacity import (
+    Retrying,
+    after_log,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_fixed,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _json_default(value: Any) -> str:
+    """JSON serializer fallback for values data_bridges_client's generated
+    to_dict() leaves as native Python objects (e.g. datetime fields, since
+    it calls pydantic's model_dump() rather than model_dump(mode="json")).
+    """
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+class WFPAPI:
+    """Light wrapper around WFP's data-bridges-client library. It needs a
+    retriever used only to decide whether to load from disk or hit the
+    network and whether to persist the network result. Token refreshing is
+    delegated to data_bridges_client's own WfpApiToken.
+
+    Args:
+        retriever: Retrieve object for interacting with WFP API
+    """
+
+    default_retry_params = {
+        "retry": retry_if_exception_type(ApiException),
+        "after": after_log(logger, logging.INFO),
+    }
+
+    def __init__(
+        self,
+        retriever: Retrieve,
+        wfp_key: str | None = None,
+        wfp_secret: str | None = None,
+    ):
+        self.retriever = retriever
+        self.retry_params = {"attempts": 1, "wait": 1}
+        if wfp_key:
+            self._wfp_key = wfp_key
+        else:
+            self._wfp_key = getenv("WFP_KEY")
+        if wfp_secret:
+            self._wfp_secret = wfp_secret
+        else:
+            self._wfp_secret = getenv("WFP_SECRET")
+        self.token = WfpApiToken(api_key=self._wfp_key, api_secret=self._wfp_secret)
+        self.configuration = Configuration()
+        self.api_client = ApiClient(self.configuration)
+        self.currency_api = CurrencyApi(self.api_client)
+        self.markets_api = MarketsApi(self.api_client)
+        self.commodities_api = CommoditiesApi(self.api_client)
+        self.market_prices_api = MarketPricesApi(self.api_client)
+
+    def get_retry_params(self) -> dict:
+        return self.retry_params
+
+    def update_retry_params(self, attempts: int, wait: int) -> dict:
+        self.retry_params["attempts"] = attempts
+        self.retry_params["wait"] = wait
+        return self.retry_params
+
+    def refresh_token(self) -> None:
+        self.configuration.access_token = self.token.refresh()
+
+    def _with_retry(self, api_method: Callable, **kwargs: Any) -> Any:
+        retryer = Retrying(
+            retry=self.default_retry_params["retry"],
+            after=self.default_retry_params["after"],
+            stop=stop_after_attempt(self.retry_params["attempts"]),
+            wait=wait_fixed(self.retry_params["wait"]),
+        )
+        for attempt in retryer:
+            with attempt:
+                try:
+                    return api_method(**kwargs)
+                except ApiException as err:
+                    if err.status not in (104, 401, 403):
+                        raise
+                    self.refresh_token()
+                    return api_method(**kwargs)
+
+    def _call(
+        self,
+        api_method: Callable,
+        model_cls: type,
+        filename: str,
+        log: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Call a data_bridges_client API method, loading from or saving to
+        disk exactly as Retrieve does, so existing fixtures keep working
+        unchanged.
+
+        Args:
+            api_method: Bound method on one of the data_bridges_client APIs
+            model_cls: Paged result model class to (de)serialize with
+            filename: Filename of saved file
+            log: Text to use in log string to describe the call
+            **kwargs: Parameters to pass to api_method
+
+        Returns:
+            An instance of model_cls, or None if there is no saved data
+        """
+        filename, _ = self.retriever.get_filename("", filename)
+        saved_path = self.retriever.saved_dir / filename
+        if self.retriever.use_saved:
+            logger.info(f"Using saved {log} in {saved_path}")
+            try:
+                return model_cls.from_dict(load_json(saved_path))
+            except FileNotFoundError:
+                return None
+        result = self._with_retry(api_method, **kwargs)
+        if self.retriever.save:
+            logger.info(f"Saving {log} in {saved_path}")
+            with open(saved_path, "w", encoding="utf-8") as f:
+                json.dump(result.to_dict(), f, default=_json_default)
+        return result
+
+    @staticmethod
+    def _countryiso3s(countryiso3: str | None) -> list:
+        if countryiso3 == "PSE":  # hack as PSE is treated by WFP as 2 areas
+            return ["PSW", "PSG"]
+        return [countryiso3]
+
+    @staticmethod
+    def _filename_and_log(
+        base_filename: str, countryiso3: str | None, page: int
+    ) -> tuple[str, str]:
+        if countryiso3 is None:
+            return f"{base_filename}_{page}.json", f"{base_filename} page {page}"
+        return (
+            f"{base_filename}_{countryiso3}_{page}.json",
+            f"{base_filename} for {countryiso3} page {page}",
+        )
+
+    def _get_all_pages(
+        self,
+        api_method: Callable,
+        model_cls: type,
+        base_filename: str,
+        countryiso3: str | None,
+        country_param: str,
+        extra_params: dict,
+    ) -> list:
+        all_items = []
+        for country in self._countryiso3s(countryiso3):
+            page = 1
+            while True:
+                kwargs = dict(extra_params)
+                kwargs["page"] = page
+                if country is not None:
+                    kwargs[country_param] = country
+                filename, log = self._filename_and_log(base_filename, country, page)
+                result = self._call(api_method, model_cls, filename, log, **kwargs)
+                items = result.items if result else None
+                if not items:
+                    break
+                all_items.extend(items)
+                page += 1
+        return all_items
+
+    def get_currencies(
+        self, countryiso3: str | None = None, currency: str | None = None
+    ) -> list[CurrencyDTO]:
+        """Get list of currencies from the WFP API.
+
+        Args:
+            countryiso3: Country for which to obtain data. Defaults to all countries.
+            currency: Currency 3-letter code to filter by. Defaults to all currencies.
+
+        Returns:
+            List of currencies from the WFP API
+        """
+        extra_params = {"currency_name": currency} if currency else {}
+        return self._get_all_pages(
+            self.currency_api.currency_list_get,
+            PagedCurrencyListDTO,
+            "Currency_List",
+            countryiso3,
+            "country_code",
+            extra_params,
+        )
+
+    def get_currency_usd_indirect_quotations(
+        self, currency: str, countryiso3: str | None = None
+    ) -> list[UsdIndirectQuotation]:
+        """Get USD indirect quotations for a currency from the WFP API.
+
+        Args:
+            currency: Currency 3-letter code
+            countryiso3: Country for which to obtain data. Defaults to all countries.
+
+        Returns:
+            List of USD indirect quotations from the WFP API
+        """
+        return self._get_all_pages(
+            self.currency_api.currency_usd_indirect_quotation_get,
+            UsdIndirectQuotationPagedResult,
+            "Currency_UsdIndirectQuotation",
+            countryiso3,
+            # this endpoint uses country_iso3, unlike every other one here which
+            # uses country_code - don't "fix" this to country_code
+            "country_iso3",
+            {"currency_name": currency},
+        )
+
+    def get_markets(self, countryiso3: str | None = None) -> list[MarketDTO]:
+        """Get list of markets from the WFP API.
+
+        Args:
+            countryiso3: Country for which to obtain data. Defaults to all countries.
+
+        Returns:
+            List of markets from the WFP API
+        """
+        return self._get_all_pages(
+            self.markets_api.markets_list_get,
+            PagedMarketListDTO,
+            "Markets_List",
+            countryiso3,
+            "country_code",
+            {},
+        )
+
+    def get_commodities(self, countryiso3: str | None = None) -> list[CommodityDTO]:
+        """Get list of commodities from the WFP API.
+
+        Args:
+            countryiso3: Country for which to obtain data. Defaults to all countries.
+
+        Returns:
+            List of commodities from the WFP API
+        """
+        return self._get_all_pages(
+            self.commodities_api.commodities_list_get,
+            PagedCommodityListDTO,
+            "Commodities_List",
+            countryiso3,
+            "country_code",
+            {},
+        )
+
+    def get_commodity_categories(
+        self, countryiso3: str | None = None
+    ) -> list[CommodityDTO]:
+        """Get list of commodity categories from the WFP API.
+
+        Args:
+            countryiso3: Country for which to obtain data. Defaults to all countries.
+
+        Returns:
+            List of commodity categories from the WFP API
+        """
+        return self._get_all_pages(
+            self.commodities_api.commodities_categories_list_get,
+            PagedCommodityListDTO,
+            "Commodities_Categories_List",
+            countryiso3,
+            "country_code",
+            {},
+        )
+
+    def get_market_prices_monthly(
+        self, countryiso3: str | None = None, **kwargs: Any
+    ) -> list[ViewExtendedMonthlyAggregatedPrice]:
+        """Get monthly aggregated market prices from the WFP API.
+
+        Args:
+            countryiso3: Country for which to obtain data. Defaults to all countries.
+            **kwargs: Additional filters accepted by
+                data_bridges_client's MarketPricesApi.market_prices_price_monthly_get,
+                e.g. market_id, commodity_id, price_type_name, currency_id,
+                price_flag, start_date, end_date, latest_value_only
+
+        Returns:
+            List of monthly aggregated market prices from the WFP API
+        """
+        return self._get_all_pages(
+            self.market_prices_api.market_prices_price_monthly_get,
+            ViewExtendedMonthlyAggregatedPricePagedResult,
+            "MarketPrices_PriceMonthly",
+            countryiso3,
+            "country_code",
+            kwargs,
+        )

{hdx_python_country-4.1.2 → hdx_python_country-4.1.3}/src/hdx/location/wfp_exchangerates.py

@@ -1,7 +1,6 @@
 import logging
 from collections.abc import Sequence
-
-from hdx.utilities.dateparse import parse_date
+from datetime import timezone
 
 from .int_timestamp import get_int_timestamp
 from .wfp_api import WFPAPI
@@ -26,11 +25,11 @@ class WFPExchangeRates:
             List of currency codes and names in WFP API
         """
         currencies = []
-        for currency in self.wfp_api.get_items("Currency/List"):
-            currency_name = currency["extendedName"]
+        for currency in self.wfp_api.get_currencies():
+            currency_name = currency.extended_name
             if currency_name:
                 currency_name = currency_name.strip()
-            currencies.append({"code": currency["name"], "name": currency_name})
+            currencies.append({"code": currency.name, "name": currency_name})
         return currencies
 
     def get_currencies(self) -> list[str]:
@@ -40,8 +39,8 @@ class WFPExchangeRates:
             List of currency codes in WFP API
         """
         currencies = []
-        for currency in self.wfp_api.get_items("Currency/List"):
-            currencies.append(currency["name"])
+        for currency in self.wfp_api.get_currencies():
+            currencies.append(currency.name)
         return currencies
 
     def get_currency_historic_rates(self, currency: str) -> dict[int, float]:
@@ -53,17 +52,19 @@ class WFPExchangeRates:
         Returns:
             Mapping from timestamp to rate
         """
-        quotes = self.wfp_api.get_items(
-            "Currency/UsdIndirectQuotation",
-            parameters={"currencyName": currency},
-        )
+        quotes = self.wfp_api.get_currency_usd_indirect_quotations(currency)
         historic_rates = {}
         for quote in reversed(quotes):
-            if not quote["isOfficial"]:
+            if not quote.is_official:
                 continue
-            date = parse_date(quote["date"])
+            date = quote.var_date
+            if date.tzinfo is None:
+                # data_bridges_client parses WFP's timezone-less date strings
+                # into naive datetimes; assume UTC to match previous
+                # parse_date-based behaviour
+                date = date.replace(tzinfo=timezone.utc)
             timestamp = get_int_timestamp(date)
-            historic_rates[timestamp] = quote["value"]
+            historic_rates[timestamp] = quote.value
         return historic_rates
 
     def get_historic_rates(self, currencies: Sequence[str]) -> dict[str, dict]:

hdx_python_country-4.1.3/tests/fixtures/wfp/Markets_List_AFG_1.json

@@ -0,0 +1,28 @@
+{
+  "items": [
+    {
+      "marketId": 179,
+      "marketName": "Kabul",
+      "marketLocalName": "Kabul",
+      "marketLatitude": 34.526011,
+      "marketLongitude": 69.176033,
+      "admin1Name": "Kabul",
+      "admin1Code": 3417,
+      "admin2Name": "Kabul",
+      "admin2Code": 33475
+    },
+    {
+      "marketId": 180,
+      "marketName": "Herat",
+      "marketLocalName": "Herat",
+      "marketLatitude": 34.348418,
+      "marketLongitude": 62.199747,
+      "admin1Name": "Herat",
+      "admin1Code": 3424,
+      "admin2Name": "Herat",
+      "admin2Code": 33520
+    }
+  ],
+  "page": 1,
+  "totalItems": 2
+}

hdx_python_country-4.1.3/tests/fixtures/wfp/Markets_List_AFG_2.json

@@ -0,0 +1,5 @@
+{
+  "items": [],
+  "page": 2,
+  "totalItems": 2
+}

{hdx_python_country-4.1.2 → hdx_python_country-4.1.3}/tests/hdx/location/test_currency.py

@@ -126,7 +126,7 @@ class TestCurrency:
         )
         rate2gbp = Currency.get_current_rate("gbp")
         assert rate2gbp != 1
-        assert abs(rate1gbp - rate2gbp) / rate1gbp < 0.008
+        assert abs(rate1gbp - rate2gbp) / rate1gbp < 0.01
         Currency.setup(
             retriever=retrievers[1],
             primary_rates_url="fail",

{hdx_python_country-4.1.2 → hdx_python_country-4.1.3}/tests/hdx/location/test_wfp_exchangerates.py

@@ -27,7 +27,7 @@ class TestWFPExchangeRates:
                 )
                 currency = "afn"
                 date = parse_date("2020-02-20")
-                wfp_api = WFPAPI(downloader, retriever)
+                wfp_api = WFPAPI(retriever)
                 wfp_api.update_retry_params(attempts=5, wait=5)
                 wfp_fx = WFPExchangeRates(wfp_api)
                 retry_params = wfp_fx.wfp_api.get_retry_params()
@@ -62,3 +62,8 @@ class TestWFPExchangeRates:
                     Currency.get_historic_rate(currency, date, ignore_timeinfo=False)
                     == 77.01
                 )
+
+                markets = wfp_api.get_markets(countryiso3="AFG")
+                assert len(markets) == 2
+                assert markets[0].market_name == "Kabul"
+                assert markets[1].market_name == "Herat"