oda-data 2.2.2__tar.gz → 2.3.0__tar.gz

{oda_data-2.2.2 → oda_data-2.3.0}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.3
 Name: oda-data
-Version: 2.2.2
+Version: 2.3.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>
 License: MIT
 Requires-Dist: cachetools>=6.2.0
-Requires-Dist: oda-reader>=1.2.2
-Requires-Dist: pandas[excel,parquet,performance]>=2.3.2
+Requires-Dist: filelock>=3.20.0
+Requires-Dist: oda-reader>=1.3.0
+Requires-Dist: pandas[excel,parquet,performance]>=2.2.0
 Requires-Dist: pydeflate>=2.1.3
 Requires-Dist: reader>=3.18
 Requires-Dist: thefuzz>=0.22.1
@@ -19,11 +20,17 @@ Description-Content-Type: text/markdown
 
 [![pypi](https://img.shields.io/pypi/v/oda_data.svg)](https://pypi.org/project/oda_data/)
 [![python](https://img.shields.io/pypi/pyversions/oda_data.svg)](https://pypi.org/project/oda_data/)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Tests](https://github.com/ONEcampaign/oda_data_package/actions/workflows/test.yml/badge.svg)](https://github.com/ONEcampaign/oda_data_package/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/ONEcampaign/oda_data_package/branch/main/graph/badge.svg)](https://codecov.io/gh/ONEcampaign/oda_data_package)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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.
 
+**Current Version: 2.3.0**
+
 **Note: This is the new version of the package (V2). This release includes many breaking changes and previous workflows
 will not work. The previous 1.5.x version remains available on PyPI and we will continue to support it at least until
 August 2025.**
@@ -34,7 +41,7 @@ of ODA, but also of how the DAC databases and tools are organised.
 
 This package aims to simplify this process and make it easier for users to get the data they need.
 
-Please submit questions, feedback or requests via 
+Please submit questions, feedback or requests via
 the [issues page](https://github.com/ONEcampaign/oda_data_package/issues).
 
 ## Getting started
@@ -47,7 +54,7 @@ The latest version of the package can be installed using pip:
 pip install oda-data --upgrade
 ```
 
-The package is compatible with Python 3.10 and above.
+The package is compatible with Python 3.11 and above.
 
 ## Basic usage
 
@@ -58,7 +65,7 @@ An object of this class can handle:
 - filtering the data for specific donors, recipients(if relevant), years.
 - returning the data in a variety of currency/prices combinations.
 
-At a minimum, the class expects users to specify years. By default it would then get 
+At a minimum, the class expects users to specify years. By default it would then get
 data for all providers, for all recipients (if applicable), as net disbursements in USD, in current prices,
 using the OECD data-explorer API.
 
@@ -124,7 +131,7 @@ data = client.get_indicators(research_indicators)
 
 ### OECDClient
 
-Over three thousand indicators are currently supported. They are mostly produced by filtering (and sometimes aggregating) data from the different DAC Tables and databases.
+Thousands of indicators are currently supported across DAC1, DAC2A, and CRS databases. These indicators are produced by filtering and sometimes aggregating data from the different DAC Tables and databases.
 
 You can get a dictionary with all supported indicators, with their code, name, description and source by using the `.available_indicators()` method:
 
@@ -169,6 +176,38 @@ from oda_data import OECDClient
 currencies = OECDClient.available_currencies()
 ```
 
+### Measures
+
+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
+- `grant_equivalent` - Grant equivalent values
+- `net_disbursement` - Net disbursements (default)
+- `net_disbursement_grant` - Net grant disbursements
+- `gross_disbursement` - Gross disbursements
+- `gross_disbursement_non_grant` - Gross non-grant disbursements
+- `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
+- `received` - Amounts received
+- `expert_commitment` - Expert commitments
+- `expert_extended` - Expert extended
+- `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.
 
@@ -294,7 +333,7 @@ You can optionally specify:
 Not specifying any or all of these parameters will return all the available data.
 
 You can refer to the examples above for DAC1 and DAC2a to understand the usage of these classes.
-**Note**: given the speed and rate-limiting of the dac-explorer APIs, it's recommended to always use the 
+**Note**: given the speed and rate-limiting of the dac-explorer APIs, it's recommended to always use the
 bulk option when using the CRS class.
 
 ```python
@@ -328,11 +367,166 @@ You can refer to the examples above for DAC1 and DAC2a to understand the usage o
 unless you're looking for something very specific.
 
 
+## Utility Functions
+
+The package provides several utility functions to enhance and enrich your ODA data analysis:
+
+### Adding Human-Readable Names
+
+Convert code columns to human-readable names:
+
+```python
+from oda_data import OECDClient, add_names_columns
+
+# Get indicator data
+client = OECDClient(years=range(2020, 2023))
+data = client.get_indicators("DAC2A.10.1010")
+
+# Add human-readable names for code columns
+data = add_names_columns(data, ["recipient_code", "provider_code"])
+```
+
+### Adding GNI Share
+
+Calculate ODA as a percentage of Gross National Income:
+
+```python
+from oda_data import OECDClient, add_gni_share_column
+
+# Create client with specific configuration
+client = OECDClient(
+    years=range(2018, 2023),
+    providers=[4, 302],  # France and USA
+    currency="USD",
+    base_year=2021
+)
+
+# Get data with GNI share column
+data = add_gni_share_column(client, "DAC1.10.1010")
+# Returns dataframe with 'gni_share_pct' column
+```
+
+### Sector Classification
+
+Add sector classifications to your data:
+
+```python
+from oda_data import add_sectors, add_broad_sectors
+
+# Add detailed sector information
+data = add_sectors(data)
+
+# Or add broad sector categories
+data = add_broad_sectors(data)
+```
+
+### Provider and Recipient Groupings
+
+Access predefined groupings of providers and recipients:
+
+```python
+from oda_data import provider_groupings, recipient_groupings
+
+# Get all provider groupings (DAC members, EU27, etc.)
+providers = provider_groupings()
+
+# Get all recipient groupings (LDCs, regions, income groups, etc.)
+recipients = recipient_groupings()
+
+# Example: Get all DAC members
+dac_members = providers["dac_members"]
+```
+
+### Cache Management
+
+Control the package's caching behavior:
+
+```python
+from oda_data import clear_cache, disable_cache, enable_cache
+
+# Clear all cached data
+clear_cache()
+
+# Temporarily disable caching (for development/testing)
+disable_cache()
+
+# Re-enable caching
+enable_cache()
+```
+
+### Compatibility with Version 1.x
+
+For users migrating from v1.x, a compatibility layer is available:
+
+```python
+from oda_data import ODAData
+
+# Use the v1.x style interface
+oda = ODAData(years=range(2018, 2022), donors=[4, 302])
+data = oda.load_indicator("total_oda_flow_net")
+```
+
+## Advanced Features
+
+### Policy Marker Analysis
+
+Extract bilateral ODA by policy marker (gender, climate, etc.):
+
+```python
+from oda_data import bilateral_policy_marker
+
+# Get gender-focused ODA (principal objective)
+gender_data = bilateral_policy_marker(
+    years=range(2015, 2023),
+    providers=[4, 302],
+    marker="gender",
+    marker_score="principal",
+    measure="gross_disbursement",
+    currency="USD",
+    base_year=2021
+)
+
+# Available markers: "gender", "environment", "nutrition", "disability", "biodiversity"
+# Available scores: "significant", "principal", "not_targeted", "not_screened",
+#                   "total_targeted", "total_allocable"
+```
+
+### Sector Imputations
+
+Access sector imputation functions for multilateral aid analysis:
+
+```python
+from oda_data.indicators.research import sector_imputations
+
+# Use specialized sector imputation functions
+# (See module documentation for available functions)
+```
+
+### AidData Integration
+
+Access project-level data from AidData's dataset:
+
+```python
+from oda_data import AidDataData, set_data_path
+
+set_data_path("path/to/data/folder")
+
+# Initialize AidData source
+aiddata = AidDataData(
+    years=range(2010, 2020),
+    recipients=["Kenya", "Tanzania"],
+    sectors=[110, 120]  # Sector codes
+)
+
+# Read the data (automatically uses bulk download)
+data = aiddata.read()
+```
+
 ## Key features
 
-- **Speed up analysis** - The package handles downloading, cleaning and loading all the data, so you can focus on the 
+- **Speed up analysis** - The package handles downloading, cleaning and loading all the data, so you can focus on the
 analysis.
-- **Get data in the currency and prices you need** - ODA data is only available in US dollars (current or constant 
+- **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)

{oda_data-2.2.2 → oda_data-2.3.0}/README.md

@@ -1,10 +1,16 @@
 [![pypi](https://img.shields.io/pypi/v/oda_data.svg)](https://pypi.org/project/oda_data/)
 [![python](https://img.shields.io/pypi/pyversions/oda_data.svg)](https://pypi.org/project/oda_data/)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Tests](https://github.com/ONEcampaign/oda_data_package/actions/workflows/test.yml/badge.svg)](https://github.com/ONEcampaign/oda_data_package/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/ONEcampaign/oda_data_package/branch/main/graph/badge.svg)](https://codecov.io/gh/ONEcampaign/oda_data_package)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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.
 
+**Current Version: 2.3.0**
+
 **Note: This is the new version of the package (V2). This release includes many breaking changes and previous workflows
 will not work. The previous 1.5.x version remains available on PyPI and we will continue to support it at least until
 August 2025.**
@@ -15,7 +21,7 @@ of ODA, but also of how the DAC databases and tools are organised.
 
 This package aims to simplify this process and make it easier for users to get the data they need.
 
-Please submit questions, feedback or requests via 
+Please submit questions, feedback or requests via
 the [issues page](https://github.com/ONEcampaign/oda_data_package/issues).
 
 ## Getting started
@@ -28,7 +34,7 @@ The latest version of the package can be installed using pip:
 pip install oda-data --upgrade
 ```
 
-The package is compatible with Python 3.10 and above.
+The package is compatible with Python 3.11 and above.
 
 ## Basic usage
 
@@ -39,7 +45,7 @@ An object of this class can handle:
 - filtering the data for specific donors, recipients(if relevant), years.
 - returning the data in a variety of currency/prices combinations.
 
-At a minimum, the class expects users to specify years. By default it would then get 
+At a minimum, the class expects users to specify years. By default it would then get
 data for all providers, for all recipients (if applicable), as net disbursements in USD, in current prices,
 using the OECD data-explorer API.
 
@@ -105,7 +111,7 @@ data = client.get_indicators(research_indicators)
 
 ### OECDClient
 
-Over three thousand indicators are currently supported. They are mostly produced by filtering (and sometimes aggregating) data from the different DAC Tables and databases.
+Thousands of indicators are currently supported across DAC1, DAC2A, and CRS databases. These indicators are produced by filtering and sometimes aggregating data from the different DAC Tables and databases.
 
 You can get a dictionary with all supported indicators, with their code, name, description and source by using the `.available_indicators()` method:
 
@@ -150,6 +156,38 @@ from oda_data import OECDClient
 currencies = OECDClient.available_currencies()
 ```
 
+### Measures
+
+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
+- `grant_equivalent` - Grant equivalent values
+- `net_disbursement` - Net disbursements (default)
+- `net_disbursement_grant` - Net grant disbursements
+- `gross_disbursement` - Gross disbursements
+- `gross_disbursement_non_grant` - Gross non-grant disbursements
+- `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
+- `received` - Amounts received
+- `expert_commitment` - Expert commitments
+- `expert_extended` - Expert extended
+- `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.
 
@@ -275,7 +313,7 @@ You can optionally specify:
 Not specifying any or all of these parameters will return all the available data.
 
 You can refer to the examples above for DAC1 and DAC2a to understand the usage of these classes.
-**Note**: given the speed and rate-limiting of the dac-explorer APIs, it's recommended to always use the 
+**Note**: given the speed and rate-limiting of the dac-explorer APIs, it's recommended to always use the
 bulk option when using the CRS class.
 
 ```python
@@ -309,11 +347,166 @@ You can refer to the examples above for DAC1 and DAC2a to understand the usage o
 unless you're looking for something very specific.
 
 
+## Utility Functions
+
+The package provides several utility functions to enhance and enrich your ODA data analysis:
+
+### Adding Human-Readable Names
+
+Convert code columns to human-readable names:
+
+```python
+from oda_data import OECDClient, add_names_columns
+
+# Get indicator data
+client = OECDClient(years=range(2020, 2023))
+data = client.get_indicators("DAC2A.10.1010")
+
+# Add human-readable names for code columns
+data = add_names_columns(data, ["recipient_code", "provider_code"])
+```
+
+### Adding GNI Share
+
+Calculate ODA as a percentage of Gross National Income:
+
+```python
+from oda_data import OECDClient, add_gni_share_column
+
+# Create client with specific configuration
+client = OECDClient(
+    years=range(2018, 2023),
+    providers=[4, 302],  # France and USA
+    currency="USD",
+    base_year=2021
+)
+
+# Get data with GNI share column
+data = add_gni_share_column(client, "DAC1.10.1010")
+# Returns dataframe with 'gni_share_pct' column
+```
+
+### Sector Classification
+
+Add sector classifications to your data:
+
+```python
+from oda_data import add_sectors, add_broad_sectors
+
+# Add detailed sector information
+data = add_sectors(data)
+
+# Or add broad sector categories
+data = add_broad_sectors(data)
+```
+
+### Provider and Recipient Groupings
+
+Access predefined groupings of providers and recipients:
+
+```python
+from oda_data import provider_groupings, recipient_groupings
+
+# Get all provider groupings (DAC members, EU27, etc.)
+providers = provider_groupings()
+
+# Get all recipient groupings (LDCs, regions, income groups, etc.)
+recipients = recipient_groupings()
+
+# Example: Get all DAC members
+dac_members = providers["dac_members"]
+```
+
+### Cache Management
+
+Control the package's caching behavior:
+
+```python
+from oda_data import clear_cache, disable_cache, enable_cache
+
+# Clear all cached data
+clear_cache()
+
+# Temporarily disable caching (for development/testing)
+disable_cache()
+
+# Re-enable caching
+enable_cache()
+```
+
+### Compatibility with Version 1.x
+
+For users migrating from v1.x, a compatibility layer is available:
+
+```python
+from oda_data import ODAData
+
+# Use the v1.x style interface
+oda = ODAData(years=range(2018, 2022), donors=[4, 302])
+data = oda.load_indicator("total_oda_flow_net")
+```
+
+## Advanced Features
+
+### Policy Marker Analysis
+
+Extract bilateral ODA by policy marker (gender, climate, etc.):
+
+```python
+from oda_data import bilateral_policy_marker
+
+# Get gender-focused ODA (principal objective)
+gender_data = bilateral_policy_marker(
+    years=range(2015, 2023),
+    providers=[4, 302],
+    marker="gender",
+    marker_score="principal",
+    measure="gross_disbursement",
+    currency="USD",
+    base_year=2021
+)
+
+# Available markers: "gender", "environment", "nutrition", "disability", "biodiversity"
+# Available scores: "significant", "principal", "not_targeted", "not_screened",
+#                   "total_targeted", "total_allocable"
+```
+
+### Sector Imputations
+
+Access sector imputation functions for multilateral aid analysis:
+
+```python
+from oda_data.indicators.research import sector_imputations
+
+# Use specialized sector imputation functions
+# (See module documentation for available functions)
+```
+
+### AidData Integration
+
+Access project-level data from AidData's dataset:
+
+```python
+from oda_data import AidDataData, set_data_path
+
+set_data_path("path/to/data/folder")
+
+# Initialize AidData source
+aiddata = AidDataData(
+    years=range(2010, 2020),
+    recipients=["Kenya", "Tanzania"],
+    sectors=[110, 120]  # Sector codes
+)
+
+# Read the data (automatically uses bulk download)
+data = aiddata.read()
+```
+
 ## Key features
 
-- **Speed up analysis** - The package handles downloading, cleaning and loading all the data, so you can focus on the 
+- **Speed up analysis** - The package handles downloading, cleaning and loading all the data, so you can focus on the
 analysis.
-- **Get data in the currency and prices you need** - ODA data is only available in US dollars (current or constant 
+- **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)

oda_data-2.3.0/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+name = "oda_data"
+version = "2.3.0"
+description = "A python package to work with Official Development Assistance data from the OECD DAC."
+requires-python = ">=3.11"
+
+license = {text = "MIT"}
+readme = "README.md"
+authors = [
+    {name = "Jorge Rivera", email = "jorge.rivera@one.org"},
+    {name = "Miguel Haro Ruiz", email = "miguel.haroruiz@one.org"}
+]
+
+dependencies = [
+    "cachetools>=6.2.0",
+    "filelock>=3.20.0",
+    "oda-reader>=1.3.0",
+    "pandas[excel,parquet,performance]>=2.2.0",
+    "pydeflate>=2.1.3",
+    "reader>=3.18",
+    "thefuzz>=0.22.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/ONEcampaign/oda_data_package"
+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"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "uv-build>=0.8.22",
+    "pre-commit>=4.0.0",
+    "ruff>=0.14.0",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-mock>=3.12.0",
+    "pytest-cov>=4.1.0",
+    "pytest-xdist>=3.5.0",
+    "freezegun>=1.4.0",
+]
+
+[tool.ruff]
+# Set the maximum line length
+line-length = 88
+
+# Target Python 3.11+
+target-version = "py311"
+
+# Exclude common directories
+exclude = [
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "*.egg-info",
+    ".pytest_cache",
+    "htmlcov",
+]
+
+[tool.ruff.lint]
+# Enable recommended rules plus extras
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "I",     # isort
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "C4",    # flake8-comprehensions
+    "SIM",   # flake8-simplify
+    "PL",    # pylint
+    "RUF",   # ruff-specific rules
+]
+
+# Ignore specific rules that might be too strict
+ignore = [
+    "E501",    # Line too long (handled by formatter)
+    "PLR0913", # Too many arguments
+    "PLR2004", # Magic value used in comparison
+    "PLC0415", # Import outside top-level (used to avoid circular imports)
+]
+
+# Allow autofix for all enabled rules
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+# Allow test files to have longer lines and more assertions
+"tests/**/*.py" = ["E501", "PLR2004", "RUF002", "RUF003"]  # Allow × in comments/docstrings
+# Allow global variable usage in __init__.py (architectural decision)
+"src/oda_data/__init__.py" = ["PLW0603", "PLW0602", "F811"]
+# Allow tmpdir reassignment pattern (Path conversion)
+"src/oda_data/tools/cache.py" = ["PLW2901"]
+# Allow loop variable binding patterns (intentional for lambda closures)
+"src/oda_data/indicators/crs/crs_functions.py" = ["B023"]
+"src/oda_data/indicators/research/sector_imputations.py" = ["B023"]
+# Allow mixedCase variable names matching official sector code names
+"src/oda_data/tools/sector_lists.py" = ["N816"]
+
+[tool.ruff.format]
+# Use double quotes for strings
+quote-style = "double"
+
+# Use spaces for indentation
+indent-style = "space"
+
+# Like Black, respect magic trailing commas
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect line endings
+line-ending = "auto"