oda-data 2.6.0__tar.gz → 2.7.0__tar.gz

{oda_data-2.6.0 → oda_data-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
-Name: oda-data
-Version: 2.6.0
+Name: oda_data
+Version: 2.7.0
 Summary: A python package to work with Official Development Assistance data from the OECD DAC.
 Author: Jorge Rivera, Miguel Haro Ruiz
 Author-email: Jorge Rivera <jorge.rivera@one.org>, Miguel Haro Ruiz <miguel.haroruiz@one.org>
@@ -25,9 +25,9 @@ Requires-Dist: pydeflate>=2.3.3
 Requires-Dist: reader>=3.18
 Requires-Dist: thefuzz>=0.22.1
 Requires-Python: >=3.11
-Project-URL: Documentation, https://github.com/ONEcampaign/oda_data_package
 Project-URL: Homepage, https://github.com/ONEcampaign/oda_data_package
 Project-URL: Repository, https://github.com/ONEcampaign/oda_data_package
+Project-URL: Documentation, https://github.com/ONEcampaign/oda_data_package
 Description-Content-Type: text/markdown
 
 [![pypi](https://img.shields.io/pypi/v/oda_data.svg)](https://pypi.org/project/oda_data/)
@@ -39,6 +39,7 @@ Description-Content-Type: text/markdown
 [![Downloads](https://static.pepy.tech/badge/oda-data)](https://pepy.tech/project/oda-data)
 
 # The ODA Data Package
+
 This is a Python package designed for accessing, processing, and analyzing Official Development Assistance (ODA) data from OECD DAC. With an intuitive API, it simplifies common tasks like retrieving ODA indicators, converting currencies, filtering data, and handling bulk downloads.
 
 **Note: This is the new version of the package (V2). This release includes many breaking changes and previous workflows
@@ -71,6 +72,7 @@ The package is compatible with Python 3.11 and above.
 Most users can get the data they need by using the `OECDClient` class.
 
 An object of this class can handle:
+
 - getting data for specific indicators (one or more)
 - filtering the data for specific donors, recipients(if relevant), years.
 - returning the data in a variety of currency/prices combinations.
@@ -160,6 +162,7 @@ OECDClient.export_available_indicators(export_folder="path/to/folder/")
 ```
 
 ### Providers
+
 You can get a dictionary with all available providers, with their code and name, by using the `.available_providers()` method:
 
 ```python
@@ -169,6 +172,7 @@ providers = OECDClient.available_providers()
 ```
 
 ### Recipients
+
 You can get a dictionary with all available recipients, with their code and name, by using the `.available_recipients()` method:
 
 ```python
@@ -178,6 +182,7 @@ recipients = OECDClient.available_recipients()
 ```
 
 ### Currencies
+
 You can get a dictionary with all available currencies, with their code and name, by using the `.available_currencies()` method:
 
 ```python
@@ -191,6 +196,7 @@ currencies = OECDClient.available_currencies()
 Different measures are available depending on the data source. Here's what each source supports:
 
 **DAC1 Measures:**
+
 - `commitment` - Total commitments
 - `commitment_grant` - Grant commitments only
 - `commitment_non_grant` - Non-grant commitments
@@ -202,10 +208,12 @@ Different measures are available depending on the data source. Here's what each
 - `received` - Amounts received
 
 **DAC2A Measures:**
+
 - `net_disbursement` - Net disbursements (default)
 - `gross_disbursement` - Gross disbursements
 
 **CRS Measures:**
+
 - `commitment` - Commitment amounts
 - `grant_equivalent` - Grant equivalent values
 - `gross_disbursement` - Gross disbursement amounts
@@ -215,16 +223,20 @@ Different measures are available depending on the data source. Here's what each
 - `export_credit` - Export credits
 
 **MultiSystem Measures:**
+
 - `commitment` - Commitments
 - `gross_disbursement` - Gross disbursements
 
 ## Accessing the data
+
 For more advanced users, you can use this package to get and work with different tables and databases from the OECD DAC.
 
 ### DAC 1
+
 The `DAC1Data` class can retrieve and return DAC 1 data.
 
 You can optionally specify:
+
 - years: to filter the data for specific years
 - providers: to filter the data for specific providers (based on their code).
 - indicators: to filter the data for a specific indicator (for DAC1 this means AIDTYPE_CODE)
@@ -232,6 +244,7 @@ You can optionally specify:
 Not specifying any or all of these parameters will return all the available data.
 
 After instantiating the object, you can call:
+
 - `download`: to download the data from the data-explorer API or the bulk download service. This method returns a DataFrame.
 - `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
 
@@ -271,11 +284,12 @@ data = dac1.read(
 )
 ```
 
-
 ### DAC 2A
+
 The `DAC2AData` class can retrieve and return DAC2a data.
 
 You can optionally specify:
+
 - years: to filter the data for specific years
 - providers: to filter the data for specific providers (based on their code).
 - recipients: to filter the data for specific recipients (based on their code).
@@ -284,6 +298,7 @@ You can optionally specify:
 Not specifying any or all of these parameters will return all the available data.
 
 After instantiating the object, you can call:
+
 - `download`: to download the data from the data-explorer API or the bulk download service. This method returns a DataFrame.
 - `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
 
@@ -333,9 +348,11 @@ data = dac2a.read(
 ```
 
 ### CRS
+
 The `CRSData` class can retrieve and return CRS data.
 
 You can optionally specify:
+
 - years: to filter the data for specific years
 - providers: to filter the data for specific providers (based on their code).
 - recipients: to filter the data for specific recipients (based on their code).
@@ -359,11 +376,12 @@ crs = CRSData(years=range(2010, 2024))
 data = crs.read(using_bulk_download=True)
 ```
 
-
 ### MultiSystem
+
 The `MultiSystemData` class can retrieve and return Providers Total Use of the Multilateral System data.
 
 You can optionally specify:
+
 - years: to filter the data for specific years
 - providers: to filter the data for specific providers (based on their code).
 - recipients: to filter the data for specific recipients (based on their code).
@@ -376,7 +394,6 @@ You can refer to the examples above for DAC1 and DAC2a to understand the usage o
 **Note**: given the speed and rate-limiting of the dac-explorer APIs, consider using the bulk option
 unless you're looking for something very specific.
 
-
 ## Utility Functions
 
 The package provides several utility functions to enhance and enrich your ODA data analysis:
@@ -543,11 +560,12 @@ data = aiddata.read()
 ## Key features
 
 - **Speed up analysis** - The package handles downloading, cleaning and loading all the data, so you can focus on the
-analysis.
+  analysis.
 - **Get data in the currency and prices you need** - ODA data is only available in US dollars (current or constant
-prices) and local currency units (current prices). The package allows you to view the data in US dollars, Euros,
-British Pounds and Canadian dollars, in both current and constant prices. We can add any other DAC currency if you
-request it via the [issues page](https://github.com/ONEcampaign/oda_data_package/issues)
+  prices) and local currency units (current prices). The package allows you to view the data in US dollars, Euros,
+  British Pounds and Canadian dollars, in both current and constant prices. We can add any other DAC currency if you
+  request it via the [issues page](https://github.com/ONEcampaign/oda_data_package/issues)
 
 ## Contributing
+
 Interested in contributing to the package? Please reach out.

{oda_data-2.6.0 → oda_data-2.7.0}/README.md

@@ -7,6 +7,7 @@
 [![Downloads](https://static.pepy.tech/badge/oda-data)](https://pepy.tech/project/oda-data)
 
 # The ODA Data Package
+
 This is a Python package designed for accessing, processing, and analyzing Official Development Assistance (ODA) data from OECD DAC. With an intuitive API, it simplifies common tasks like retrieving ODA indicators, converting currencies, filtering data, and handling bulk downloads.
 
 **Note: This is the new version of the package (V2). This release includes many breaking changes and previous workflows
@@ -39,6 +40,7 @@ The package is compatible with Python 3.11 and above.
 Most users can get the data they need by using the `OECDClient` class.
 
 An object of this class can handle:
+
 - getting data for specific indicators (one or more)
 - filtering the data for specific donors, recipients(if relevant), years.
 - returning the data in a variety of currency/prices combinations.
@@ -128,6 +130,7 @@ OECDClient.export_available_indicators(export_folder="path/to/folder/")
 ```
 
 ### Providers
+
 You can get a dictionary with all available providers, with their code and name, by using the `.available_providers()` method:
 
 ```python
@@ -137,6 +140,7 @@ providers = OECDClient.available_providers()
 ```
 
 ### Recipients
+
 You can get a dictionary with all available recipients, with their code and name, by using the `.available_recipients()` method:
 
 ```python
@@ -146,6 +150,7 @@ recipients = OECDClient.available_recipients()
 ```
 
 ### Currencies
+
 You can get a dictionary with all available currencies, with their code and name, by using the `.available_currencies()` method:
 
 ```python
@@ -159,6 +164,7 @@ currencies = OECDClient.available_currencies()
 Different measures are available depending on the data source. Here's what each source supports:
 
 **DAC1 Measures:**
+
 - `commitment` - Total commitments
 - `commitment_grant` - Grant commitments only
 - `commitment_non_grant` - Non-grant commitments
@@ -170,10 +176,12 @@ Different measures are available depending on the data source. Here's what each
 - `received` - Amounts received
 
 **DAC2A Measures:**
+
 - `net_disbursement` - Net disbursements (default)
 - `gross_disbursement` - Gross disbursements
 
 **CRS Measures:**
+
 - `commitment` - Commitment amounts
 - `grant_equivalent` - Grant equivalent values
 - `gross_disbursement` - Gross disbursement amounts
@@ -183,16 +191,20 @@ Different measures are available depending on the data source. Here's what each
 - `export_credit` - Export credits
 
 **MultiSystem Measures:**
+
 - `commitment` - Commitments
 - `gross_disbursement` - Gross disbursements
 
 ## Accessing the data
+
 For more advanced users, you can use this package to get and work with different tables and databases from the OECD DAC.
 
 ### DAC 1
+
 The `DAC1Data` class can retrieve and return DAC 1 data.
 
 You can optionally specify:
+
 - years: to filter the data for specific years
 - providers: to filter the data for specific providers (based on their code).
 - indicators: to filter the data for a specific indicator (for DAC1 this means AIDTYPE_CODE)
@@ -200,6 +212,7 @@ You can optionally specify:
 Not specifying any or all of these parameters will return all the available data.
 
 After instantiating the object, you can call:
+
 - `download`: to download the data from the data-explorer API or the bulk download service. This method returns a DataFrame.
 - `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
 
@@ -239,11 +252,12 @@ data = dac1.read(
 )
 ```
 
-
 ### DAC 2A
+
 The `DAC2AData` class can retrieve and return DAC2a data.
 
 You can optionally specify:
+
 - years: to filter the data for specific years
 - providers: to filter the data for specific providers (based on their code).
 - recipients: to filter the data for specific recipients (based on their code).
@@ -252,6 +266,7 @@ You can optionally specify:
 Not specifying any or all of these parameters will return all the available data.
 
 After instantiating the object, you can call:
+
 - `download`: to download the data from the data-explorer API or the bulk download service. This method returns a DataFrame.
 - `read`: to read data as stored in the specified folder. If the data is not available, it will be downloaded.
 
@@ -301,9 +316,11 @@ data = dac2a.read(
 ```
 
 ### CRS
+
 The `CRSData` class can retrieve and return CRS data.
 
 You can optionally specify:
+
 - years: to filter the data for specific years
 - providers: to filter the data for specific providers (based on their code).
 - recipients: to filter the data for specific recipients (based on their code).
@@ -327,11 +344,12 @@ crs = CRSData(years=range(2010, 2024))
 data = crs.read(using_bulk_download=True)
 ```
 
-
 ### MultiSystem
+
 The `MultiSystemData` class can retrieve and return Providers Total Use of the Multilateral System data.
 
 You can optionally specify:
+
 - years: to filter the data for specific years
 - providers: to filter the data for specific providers (based on their code).
 - recipients: to filter the data for specific recipients (based on their code).
@@ -344,7 +362,6 @@ You can refer to the examples above for DAC1 and DAC2a to understand the usage o
 **Note**: given the speed and rate-limiting of the dac-explorer APIs, consider using the bulk option
 unless you're looking for something very specific.
 
-
 ## Utility Functions
 
 The package provides several utility functions to enhance and enrich your ODA data analysis:
@@ -511,11 +528,12 @@ data = aiddata.read()
 ## Key features
 
 - **Speed up analysis** - The package handles downloading, cleaning and loading all the data, so you can focus on the
-analysis.
+  analysis.
 - **Get data in the currency and prices you need** - ODA data is only available in US dollars (current or constant
-prices) and local currency units (current prices). The package allows you to view the data in US dollars, Euros,
-British Pounds and Canadian dollars, in both current and constant prices. We can add any other DAC currency if you
-request it via the [issues page](https://github.com/ONEcampaign/oda_data_package/issues)
+  prices) and local currency units (current prices). The package allows you to view the data in US dollars, Euros,
+  British Pounds and Canadian dollars, in both current and constant prices. We can add any other DAC currency if you
+  request it via the [issues page](https://github.com/ONEcampaign/oda_data_package/issues)
 
 ## Contributing
+
 Interested in contributing to the package? Please reach out.

{oda_data-2.6.0 → oda_data-2.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oda_data"
-version = "2.6.0"
+version = "2.7.0"
 description = "A python package to work with Official Development Assistance data from the OECD DAC."
 requires-python = ">=3.11"
 
@@ -42,14 +42,14 @@ Repository = "https://github.com/ONEcampaign/oda_data_package"
 Documentation = "https://github.com/ONEcampaign/oda_data_package"
 
 [build-system]
-requires = ["uv_build>=0.8.22,<0.9.0"]
+requires = ["uv_build>=0.11.8,<0.12"]
 build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
-    "uv-build>=0.9.17",
     "pre-commit>=4.5.0",
     "ruff>=0.14.9",
+    "ty>=0.0.33",
     "mkdocs-material>=9.7.0",
 ]
 test = [
@@ -67,6 +67,9 @@ line-length = 88
 # Target Python 3.11+
 target-version = "py311"
 
+# Lint/format notebooks too
+extend-include = ["*.ipynb"]
+
 # Exclude common directories
 exclude = [
     ".git",
@@ -94,14 +97,21 @@ select = [
     "SIM",   # flake8-simplify
     "PL",    # pylint
     "RUF",   # ruff-specific rules
+    "ERA",   # eradicate (commented-out code)
+    "PERF",  # perflint
+    "ANN",   # flake8-annotations (require type hints on public APIs)
 ]
 
 # Ignore specific rules that might be too strict
 ignore = [
     "E501",    # Line too long (handled by formatter)
     "PLR0913", # Too many arguments
+    "PLR0912", # Too many branches
+    "PLR0914", # Too many locals
+    "PLR0915", # Too many statements
     "PLR2004", # Magic value used in comparison
     "PLC0415", # Import outside top-level (used to avoid circular imports)
+    "ANN401",  # Allow `Any` in typed signatures
 ]
 
 # Allow autofix for all enabled rules
@@ -110,7 +120,7 @@ unfixable = []
 
 [tool.ruff.lint.per-file-ignores]
 # Allow test files to have longer lines and more assertions
-"tests/**/*.py" = ["E501", "PLR2004", "RUF002", "RUF003", "PLW0603"]  # Allow × in comments/docstrings; PLW0603 for spawn-pool worker globals
+"tests/**/*.py" = ["ANN", "E501", "PLR2004", "RUF002", "RUF003", "PLW0603", "ERA001"]  # Tests don't need annotations (ANN); allow × in comments/docstrings; PLW0603 for spawn-pool worker globals; ERA001 for intentional commented-out fixtures
 # Allow global variable usage in __init__.py (architectural decision)
 "src/oda_data/__init__.py" = ["PLW0603", "PLW0602", "F811"]
 # Lazy module-level state (override flag, chained-root cache, auto-migrate gate, 5GB warning latch).
@@ -126,6 +136,9 @@ unfixable = []
 # Allow mixedCase variable names matching official sector code names
 "src/oda_data/tools/sector_lists.py" = ["N816"]
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
 [tool.ruff.format]
 # Use double quotes for strings
 quote-style = "double"
@@ -139,5 +152,86 @@ skip-magic-trailing-comma = false
 # Like Black, automatically detect line endings
 line-ending = "auto"
 
-# Note: pytest configuration lives in `pytest.ini` (which takes precedence over
-# this file). Markers and addopts must be added there, not here.
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.src]
+include = ["src/oda_data"]
+
+# NOTE: The following two sections are borrowed from the bblocks-projects
+# `project` preset (the `package` preset omits them). This is a pandas/numpy-
+# heavy package, so the same false-positive cascade from those libraries'
+# incomplete stubs applies here. Kept as a deliberate divergence.
+[tool.ty.analysis]
+# Replace pandas / numpy type information with `Any` to eliminate the cascade
+# of false positives from those libraries' incomplete or absent stubs without
+# disabling type checking on our own code.
+# https://docs.astral.sh/ty/reference/configuration/
+replace-imports-with-any = [
+    "pandas",
+    "pandas.**",
+    "numpy",
+    "numpy.**",
+]
+
+[tool.ty.rules]
+# These warn-by-default rules fire frequently on dynamic dataframe / dict
+# patterns common in this codebase. Demoted to ignore.
+possibly-missing-attribute = "ignore"
+possibly-unresolved-reference = "ignore"
+
+[tool.pytest.ini_options]
+# Test discovery patterns
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+# Test execution options. Integration/network tests are deselected by default.
+addopts = """
+    -v
+    --strict-markers
+    --tb=short
+    --cov=src/oda_data
+    --cov-report=term-missing
+    --cov-report=html
+    --cov-branch
+    -m "not integration and not network"
+"""
+
+# Custom markers for organizing tests
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests that call real OECD API (deselected by default)",
+    "network: marks tests requiring live network access (opt-in via RUN_NETWORK_TESTS=1; deselected by default)",
+    "unit: marks tests as unit tests",
+    "cache: marks tests related to caching functionality",
+    "validation: marks tests related to input validation",
+    "cleaning: marks tests related to data cleaning",
+]
+
+# Directories not searched for tests
+norecursedirs = [".git", ".venv", "venv", "__pycache__", "*.egg-info", ".pytest_cache", "htmlcov"]
+
+[tool.coverage.run]
+source = ["src/oda_data"]
+branch = true
+omit = [
+    "*/tests/*",
+    "*/__init__.py",
+    "*/config.py",
+    "*/logger.py",
+]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]

{oda_data-2.6.0 → oda_data-2.7.0}/src/oda_data/__init__.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import warnings
+from pathlib import Path
 
 from oda_data import cache
 from oda_data.api.oecd import OECDClient
@@ -51,7 +54,7 @@ def enable_cache() -> None:
     _enable("all")
 
 
-def set_data_path(path) -> None:
+def set_data_path(path: str | Path) -> None:
     """Set the path for data outputs (parquet exports).
 
     Deprecated: cache location is now controlled via set_cache_root() or
@@ -60,8 +63,6 @@ def set_data_path(path) -> None:
     """
     global _DEPRECATION_WARNED_SET_DATA_PATH
 
-    from pathlib import Path
-
     from pydeflate import set_pydeflate_path
 
     from oda_data.config import ODAPaths

{oda_data-2.6.0 → oda_data-2.7.0}/src/oda_data/api/oecd.py

@@ -1,6 +1,8 @@
+from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass
 from pathlib import Path
+from typing import cast
 
 import pandas as pd
 
@@ -29,7 +31,7 @@ source_to_module = {
     "CRS": crs_functions,
 }
 
-READERS: dict[str, callable] = {
+READERS: dict[str, Callable] = {
     "DAC1": DAC1Data,
     "DAC2A": DAC2AData,
     "CRS": CRSData,
@@ -63,7 +65,7 @@ def load_indicators() -> dict[str, dict]:
 
     # Merge each inner dictionary into the combined dictionary
     for indicators in (dac1_indicators, dac2a_indicators, crs_indicators):
-        for _k, v in indicators.items():
+        for v in indicators.values():
             combined |= v
 
     return combined
@@ -122,9 +124,9 @@ class OECDClient:
                     continue
                 if self.use_bulk_download and source == "DAC2A":
                     continue
-                to_filter = []
-                for measure in self.measure:
-                    to_filter.append(get_measure_filter(source, measure))
+                to_filter = [
+                    get_measure_filter(source, measure) for measure in self.measure
+                ]
                 if to_filter is not None:
                     filters[source].append((col, "in", to_filter))
 
@@ -170,7 +172,7 @@ class OECDClient:
     def _process_data(self, indicator: str) -> None:
         """Apply custom processing functions to the loaded data."""
         custom_function = self._indicators[indicator].get("custom_function")
-        if (len(custom_function) < 1) or custom_function is None:
+        if custom_function is None or len(custom_function) < 1:
             return
 
         main_source = self._indicators[indicator]["sources"][0]
@@ -193,7 +195,7 @@ class OECDClient:
             self.indicators_data[indicator]
         )
 
-    def _group_data(self, indicator: str):
+    def _group_data(self, indicator: str) -> None:
         """Group the data to create semi-aggregated indicators (for valid sources)"""
         main_source = self._indicators[indicator]["sources"][0]
 
@@ -203,7 +205,7 @@ class OECDClient:
         self.indicators_data[indicator] = group_data_based_on_indicator(
             data=self.indicators_data[indicator],
             indicator_code=indicator,
-            measures=self.measure,
+            measures=cast("list[str] | Measure", self.measure),
         )
 
     def _convert_units(self, indicator: str) -> None:
@@ -217,7 +219,7 @@ class OECDClient:
         )
 
     @property
-    def arguments(self):
+    def arguments(self) -> dict:
         """Returns the arguments used by the object"""
         return {
             "years": self.years,
@@ -306,7 +308,7 @@ class OECDClient:
 
         return pd.concat(
             [
-                d.assign(one_indicator=i).dropna(axis=1, how="all")
+                cast(pd.DataFrame, d).assign(one_indicator=i).dropna(axis=1, how="all")
                 for i, d in self.indicators_data.items()
                 if i in indicators
             ],

{oda_data-2.6.0 → oda_data-2.7.0}/src/oda_data/api/representations.py

@@ -1,10 +1,10 @@
 class _ODAList(list):
-    def __repr__(self):
+    def __repr__(self) -> str:
         # Return the elements with a line break between them
         return "[\n" + ",\n".join(str(x) for x in self) + "\n]"
 
 
 class _ODADict(dict):
-    def __repr__(self):
+    def __repr__(self) -> str:
         # Return the elements with a line break between them
         return "{\n" + ",\n".join(f"{k}: {v}" for k, v in self.items()) + "\n}"