oda-data 2.8.2__tar.gz → 3.0.0__tar.gz

oda_data-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 ONE Campaign
+
+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.

oda_data-3.0.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: oda_data
+Version: 3.0.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-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: duckdb>=1.1.0
+Requires-Dist: oda-reader>=1.15.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: pyarrow>=17.0.0
+Requires-Dist: pydeflate>=2.7.0
+Requires-Dist: readerkit>=0.1.0
+Requires-Dist: resolvekit>=0.1.13
+Requires-Dist: polars>=1.0.0 ; extra == 'polars'
+Requires-Python: >=3.12
+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/blob/main/docs/docs/index.md
+Provides-Extra: polars
+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/)
+[![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)
+
+# oda-data
+
+oda-data gives you official development assistance (ODA) figures from the OECD's DAC tables by name, for any years and providers, in any currency, with a record of where each number came from.
+
+```text
+    provider_name  year             basis     value
+0          France  2024  grant_equivalent  15448.26
+1         Germany  2024  grant_equivalent  32836.11
+2  United Kingdom  2024  grant_equivalent  17991.79
+3   United States  2024  grant_equivalent  65475.37
+```
+
+```python
+import oda_data as oda
+
+df = oda.get("oecd.dac1.total_oda", years=2024, providers=["USA", "DEU", "GBR", "FRA"])
+print(df[["provider_name", "year", "basis", "value"]])
+```
+
+Values are USD millions. The first call downloads the OECD's DAC1 table (about 10 MB) and keeps it on disk.
+
+## Install
+
+```bash
+pip install oda-data
+```
+
+oda-data needs Python 3.12 or later. `pip install "oda-data[polars]"` adds `Query.to_polars()`.
+
+## What it does
+
+Most ODA figures depend on reading a DAC table correctly: DAC1 for official totals, DAC2A for what recipients receive, the CRS for sectors and channels. Each table has its own codes, bases, aggregate rows, and lines that nest inside each other. oda-data holds those rules in more than 40 named indicators, such as `oecd.dac1.total_oda`, `oecd.crs.bilateral_oda`, and `one.crs.imputed_multilateral_oda`, so one call returns one tidy table.
+
+```python
+import oda_data as oda
+
+dac = oda.groups.dac_countries
+
+# Each DAC country and the DAC total, in constant 2024 euros
+oda.get(
+    "oecd.dac1.total_oda",
+    years=range(2015, 2025),
+    providers=[dac, oda.total(dac)],
+    unit=oda.constant("EUR", 2024),
+)
+
+# Bilateral ODA to Kenya by broad sector
+oda.get("oecd.crs.bilateral_oda", years=2023, recipients="KEN", by=["broad_sector"])
+```
+
+Every result has the same columns, converts money provider by provider before any sum, and refuses a question its table cannot answer with an error that names the indicator that can. [oda-reader](https://github.com/ONEcampaign/oda_reader) downloads and caches the OECD tables, and [pydeflate](https://github.com/jm-rivera/pydeflate) supplies deflators and exchange rates from the same DAC1 release.
+
+oda-data is the wrong tool for a pipeline that needs the raw OECD tables. Read those with oda-reader.
+
+## Documentation
+
+- [Tutorial](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/tutorial.md): chart ten years of G7 aid
+- [How-to guides](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/how-to/find-an-indicator.md): finding the indicator for a question, units, groups, sectors, imputed multilateral sectors, records, provenance, offline use
+- [Indicators](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/reference/indicators.md) and the [public API](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/reference/api.md)
+- [Counting rules](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/explanation/counting-rules.md): which rows count, and why
+- [Migrating from 2.x](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/migration.md): the 3.0 call for any 2.x code, and the numbers that change
+
+3.0 replaces the 2.x API. `oda.search("DAC1.10.1010")` returns the 3.0 call for any 2.x indicator code.
+
+Questions and bug reports go to the [issue tracker](https://github.com/ONEcampaign/oda_data_package/issues). [CONTRIBUTING.md](https://github.com/ONEcampaign/oda_data_package/blob/main/CONTRIBUTING.md) explains how to work on the package.
+
+MIT licence. See [LICENSE](https://github.com/ONEcampaign/oda_data_package/blob/main/LICENSE).

oda_data-3.0.0/README.md

@@ -0,0 +1,72 @@
+[![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/)
+[![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)
+
+# oda-data
+
+oda-data gives you official development assistance (ODA) figures from the OECD's DAC tables by name, for any years and providers, in any currency, with a record of where each number came from.
+
+```text
+    provider_name  year             basis     value
+0          France  2024  grant_equivalent  15448.26
+1         Germany  2024  grant_equivalent  32836.11
+2  United Kingdom  2024  grant_equivalent  17991.79
+3   United States  2024  grant_equivalent  65475.37
+```
+
+```python
+import oda_data as oda
+
+df = oda.get("oecd.dac1.total_oda", years=2024, providers=["USA", "DEU", "GBR", "FRA"])
+print(df[["provider_name", "year", "basis", "value"]])
+```
+
+Values are USD millions. The first call downloads the OECD's DAC1 table (about 10 MB) and keeps it on disk.
+
+## Install
+
+```bash
+pip install oda-data
+```
+
+oda-data needs Python 3.12 or later. `pip install "oda-data[polars]"` adds `Query.to_polars()`.
+
+## What it does
+
+Most ODA figures depend on reading a DAC table correctly: DAC1 for official totals, DAC2A for what recipients receive, the CRS for sectors and channels. Each table has its own codes, bases, aggregate rows, and lines that nest inside each other. oda-data holds those rules in more than 40 named indicators, such as `oecd.dac1.total_oda`, `oecd.crs.bilateral_oda`, and `one.crs.imputed_multilateral_oda`, so one call returns one tidy table.
+
+```python
+import oda_data as oda
+
+dac = oda.groups.dac_countries
+
+# Each DAC country and the DAC total, in constant 2024 euros
+oda.get(
+    "oecd.dac1.total_oda",
+    years=range(2015, 2025),
+    providers=[dac, oda.total(dac)],
+    unit=oda.constant("EUR", 2024),
+)
+
+# Bilateral ODA to Kenya by broad sector
+oda.get("oecd.crs.bilateral_oda", years=2023, recipients="KEN", by=["broad_sector"])
+```
+
+Every result has the same columns, converts money provider by provider before any sum, and refuses a question its table cannot answer with an error that names the indicator that can. [oda-reader](https://github.com/ONEcampaign/oda_reader) downloads and caches the OECD tables, and [pydeflate](https://github.com/jm-rivera/pydeflate) supplies deflators and exchange rates from the same DAC1 release.
+
+oda-data is the wrong tool for a pipeline that needs the raw OECD tables. Read those with oda-reader.
+
+## Documentation
+
+- [Tutorial](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/tutorial.md): chart ten years of G7 aid
+- [How-to guides](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/how-to/find-an-indicator.md): finding the indicator for a question, units, groups, sectors, imputed multilateral sectors, records, provenance, offline use
+- [Indicators](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/reference/indicators.md) and the [public API](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/reference/api.md)
+- [Counting rules](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/explanation/counting-rules.md): which rows count, and why
+- [Migrating from 2.x](https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/migration.md): the 3.0 call for any 2.x code, and the numbers that change
+
+3.0 replaces the 2.x API. `oda.search("DAC1.10.1010")` returns the 3.0 call for any 2.x indicator code.
+
+Questions and bug reports go to the [issue tracker](https://github.com/ONEcampaign/oda_data_package/issues). [CONTRIBUTING.md](https://github.com/ONEcampaign/oda_data_package/blob/main/CONTRIBUTING.md) explains how to work on the package.
+
+MIT licence. See [LICENSE](https://github.com/ONEcampaign/oda_data_package/blob/main/LICENSE).

{oda_data-2.8.2 → oda_data-3.0.0}/pyproject.toml

@@ -1,35 +1,33 @@
 [project]
 name = "oda_data"
-version = "2.8.2"
+version = "3.0.0"
 description = "A python package to work with Official Development Assistance data from the OECD DAC."
-requires-python = ">=3.11"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
 readme = "README.md"
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3 :: Only",
     "Topic :: Scientific/Engineering",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "cachetools>=6.2.0",
-    "filelock>=3.20.0",
-    "oda-reader>=1.9.0",
-    "platformdirs>=4.0.0",
-    "pandas[excel,parquet,performance]>=2.2.0",
-    "pydeflate>=2.3.3",
-    "reader>=3.18",
+    "duckdb>=1.1.0",
+    "oda-reader>=1.15.0",
+    "pandas>=2.2.0",
+    "pyarrow>=17.0.0",
+    "pydeflate>=2.7.0",
+    "readerkit>=0.1.0",
+    "resolvekit>=0.1.13",
 ]
 
-[project.license]
-text = "MIT"
-
 [[project.authors]]
 name = "Jorge Rivera"
 email = "jorge.rivera@one.org"
@@ -38,13 +36,16 @@ email = "jorge.rivera@one.org"
 name = "Miguel Haro Ruiz"
 email = "miguel.haroruiz@one.org"
 
+[project.optional-dependencies]
+polars = ["polars>=1.0.0"]
+
 [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"
+Documentation = "https://github.com/ONEcampaign/oda_data_package/blob/main/docs/docs/index.md"
 
 [build-system]
-requires = ["uv_build>=0.11.8,<0.12"]
+requires = ["uv_build>=0.12.0,<0.13"]
 build-backend = "uv_build"
 
 [dependency-groups]
@@ -56,15 +57,11 @@ dev = [
 ]
 test = [
     "pytest>=8.0.0",
-    "pytest-mock>=3.12.0",
     "pytest-cov>=4.1.0",
-    "pytest-xdist>=3.5.0",
-    "freezegun>=1.4.0",
-]
-maintenance = [
-    "resolvekit==0.1.12 ; python_version >= '3.12'",
-    "pyyaml>=6.0 ; python_version >= '3.12'",
+    "polars>=1.0.0",
+    "matplotlib>=3.8.0",
 ]
+maintenance = ["pyyaml>=6.0"]
 
 [tool.uv]
 default-groups = [
@@ -74,7 +71,7 @@ default-groups = [
 
 [tool.ruff]
 line-length = 88
-target-version = "py311"
+target-version = "py312"
 extend-include = ["*.ipynb"]
 exclude = [
     ".git",
@@ -123,23 +120,12 @@ unfixable = []
     "ANN",
     "E501",
     "PLR2004",
-    "RUF002",
-    "RUF003",
-    "PLW0603",
-    "ERA001",
 ]
 "src/oda_data/__init__.py" = [
     "PLW0603",
     "PLW0602",
     "F811",
 ]
-"src/oda_data/cache/config.py" = ["PLW0603"]
-"src/oda_data/cache/api.py" = ["PLW0603"]
-"src/oda_data/tools/cache.py" = ["PLW2901"]
-"src/oda_data/api/oecd.py" = ["PLR0912"]
-"src/oda_data/indicators/crs/crs_functions.py" = ["B023"]
-"src/oda_data/indicators/research/sector_imputations.py" = ["B023"]
-"src/oda_data/tools/sector_lists.py" = ["N816"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -151,10 +137,13 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.ty.environment]
-python-version = "3.11"
+python-version = "3.12"
 
 [tool.ty.src]
-include = ["src/oda_data"]
+include = [
+    "src/oda_data",
+    "tests/unit/typing_checks.py",
+]
 
 [tool.ty.analysis]
 replace-imports-with-any = [
@@ -170,28 +159,9 @@ possibly-unresolved-reference = "ignore"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-python_files = ["test_*.py"]
-python_classes = ["Test*"]
-python_functions = ["test_*"]
-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"
-"""
-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",
-]
+addopts = "-ra --strict-markers --strict-config"
+filterwarnings = ["error"]
+markers = ["data: reads the real OECD tables through the oda-reader cache (needs a warm cache; ODA_DATA_REQUIRE_DATA=1 turns a skip into a failure)"]
 norecursedirs = [
     ".git",
     ".venv",
@@ -205,22 +175,17 @@ norecursedirs = [
 [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",
 ]
+
+[tool.codespell]
+ignore-words-list = "NotIn,Programm"

oda_data-3.0.0/pyproject.toml.orig

@@ -0,0 +1,179 @@
+[project]
+name = "oda_data"
+version = "3.0.0"
+description = "A python package to work with Official Development Assistance data from the OECD DAC."
+requires-python = ">=3.12"
+
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [
+    {name = "Jorge Rivera", email = "jorge.rivera@one.org"},
+    {name = "Miguel Haro Ruiz", email = "miguel.haroruiz@one.org"}
+]
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "duckdb>=1.1.0",
+    "oda-reader>=1.15.0",
+    "pandas>=2.2.0",
+    "pyarrow>=17.0.0",
+    "pydeflate>=2.7.0",
+    "readerkit>=0.1.0",
+    "resolvekit>=0.1.13",
+]
+
+[project.optional-dependencies]
+polars = ["polars>=1.0.0"]
+
+[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/blob/main/docs/docs/index.md"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.0",
+    "ruff>=0.14.9",
+    "ty>=0.0.33",
+    "mkdocs-material>=9.7.0",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "polars>=1.0.0",
+    # The tutorial's chart example, which tests/docs runs.
+    "matplotlib>=3.8.0",
+]
+# Maintenance-only tooling for scripts/refresh_channel_crosswalk.py.
+maintenance = [
+    "pyyaml>=6.0",
+]
+
+[tool.uv]
+default-groups = ["dev", "test"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+extend-include = ["*.ipynb"]
+exclude = [
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "*.egg-info",
+    ".pytest_cache",
+    "htmlcov",
+]
+
+[tool.ruff.lint]
+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
+    "ERA",   # eradicate (commented-out code)
+    "PERF",  # perflint
+    "ANN",   # flake8-annotations (require type hints on public APIs)
+]
+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 (the package defers heavy imports)
+    "ANN401",  # Allow `Any` in typed signatures
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ANN", "E501", "PLR2004"]
+# The module-level __getattr__ loads names lazily and caches them in globals().
+"src/oda_data/__init__.py" = ["PLW0603", "PLW0602", "F811"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.src]
+include = ["src/oda_data", "tests/unit/typing_checks.py"]
+
+# pandas and numpy stubs are incomplete; treating them as Any avoids a cascade
+# of false positives without disabling checks on this package's own code.
+[tool.ty.analysis]
+replace-imports-with-any = [
+    "pandas",
+    "pandas.**",
+    "numpy",
+    "numpy.**",
+]
+
+[tool.ty.rules]
+possibly-missing-attribute = "ignore"
+possibly-unresolved-reference = "ignore"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config"
+filterwarnings = ["error"]
+markers = [
+    "data: reads the real OECD tables through the oda-reader cache (needs a warm cache; ODA_DATA_REQUIRE_DATA=1 turns a skip into a failure)",
+]
+norecursedirs = [".git", ".venv", "venv", "__pycache__", "*.egg-info", ".pytest_cache", "htmlcov"]
+
+[tool.coverage.run]
+source = ["src/oda_data"]
+branch = true
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+[tool.codespell]
+# NotIn is a filter class in _model.py; Programm is a deliberate typo that
+# tests/unit/test_resolve.py feeds the resolver.
+ignore-words-list = "NotIn,Programm"