pyproject.toml

[project]
name = "oda_reader"
version = "1.10.0"
description = "A simple package to import ODA data from the OECD's API and AidData's database"
readme = "README.md"
license = "MIT"
authors = [
    { name = "Jorge Rivera", email = "jorge.rivera@one.org" }
]
requires-python = ">=3.12"
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3 :: Only",
    "Topic :: Scientific/Engineering",
    "Topic :: Software Development :: Libraries :: Python Modules",
]
dependencies = [
    "filelock>=3.20.3",
    "joblib>=1.4",
    "openpyxl>=3.1.0",
    "pandas>=2.2.0",
    "pyarrow>=23.0.1",
    "readerkit>=0.1.0",
    "requests>=2.33.0",
    "requests-cache>=1.2.0",
    "inflate64>=1.0.0",
]


[build-system]
requires = ["uv_build>=0.11.8,<0.12"]
build-backend = "uv_build"

[dependency-groups]
dev = [
    "pandas-stubs>=2.3.3",
    "platformdirs>=4.5.0",
    "pre-commit>=4.0.0",
    "pytest>=9.0.3",
    "pytest-mock>=3.15.1",
    "ruff>=0.14.0",
    "ty>=0.0.33",
]
docs = [
    "mkdocs>=1.5.0",
    "mkdocs-material>=9.5.0",
    "mkdocstrings[python]>=0.24.0",
]
test = [
    "freezegun>=1.4.0",
    "pytest>=9.0.3",
    "pytest-mock>=3.12",
    "pytest-cov>=4.1",
    "pytest-xdist>=3.5",
]

[tool.uv]
constraint-dependencies = [
    "urllib3>=2.7.0",
    "virtualenv>=20.36.1",
    "pygments>=2.20.0",
    "idna>=3.15",
    "pymdown-extensions>=11.0.0",
]

[tool.ruff]
# Set the maximum line length
line-length = 88

# Target Python 3.12+
target-version = "py312"

# Lint and format Jupyter notebooks too
extend-include = ["*.ipynb"]

# Exclude common directories
exclude = [
    ".git",
    ".venv",
    "venv",
    "__pycache__",
    "build",
    "dist",
    "*.egg-info",
    ".pytest_cache",
    "htmlcov",
    ".cache",
]

[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
    "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
    "ANN401",  # Allow `Any` in typed signatures
    "RUF022",  # Unsorted __all__ (intentional grouping by category)
    "RUF013",  # Implicit Optional (cleaner syntax for defaults)
]

# Allow autofix for all enabled rules
fixable = ["ALL"]
unfixable = []

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.per-file-ignores]
# Tests don't need annotations, pylint-magic-value gates, or line-length limits.
# PLC0415: in-test imports are a deliberate pattern for monkeypatching module
# objects (monkeypatch.setattr needs the module, not just the symbol).
"tests/**/*.py" = ["ANN", "PLR2004", "E501", "PLC0415"]
"docs/examples/**/*.py" = ["E501"]
# Notebooks: exploration style — don't require annotations; allow REPL patterns.
"**/*.ipynb" = ["ANN", "F401", "F811", "E402"]
# Allow global variable usage in singleton-managing modules (architectural decision)
"src/oda_reader/_cache/*.py" = ["PLW0603"]
"src/oda_reader/common.py" = ["PLW0603"]
"src/oda_reader/_http_primitives.py" = ["PLW0603"]
# Allow try-except without from (external libraries may not support cause chaining)
"src/oda_reader/download/download_tools.py" = ["B904"]
# Allow camelcase import in tools (QueryBuilder is the standard name)
"src/oda_reader/tools.py" = ["N813"]

[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"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
pythonpath = ["."]
markers = [
    "unit: Fast unit tests (no external dependencies)",
    "integration: Tests that call real OECD API",
    "network: Tests that require live network access (opt-in via RUN_NETWORK_TESTS=1)",
    "slow: Long-running tests (bulk downloads)",
    "cache: Tests that verify cache behavior",
]
addopts = [
    "-v",
    "--strict-markers",
    "-m", "not integration",
]

[tool.ty.environment]
python-version = "3.12"

[tool.ty.src]
include = ["src/oda_reader", "scripts"]

[tool.ty.analysis]
# Replace pandas / numpy type information with `Any`. Eliminates the cascade of
# false positives from those libraries' incomplete or absent stubs without
# disabling type checking on our own code. oda_reader is pandas-heavy, so this
# keeps the remaining ty diagnostics genuine.
# 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. Demoted to ignore.
possibly-missing-attribute = "ignore"
possibly-unresolved-reference = "ignore"

[tool.coverage.run]
source = ["src"]
branch = true
omit = [
    "*/tests/*",
    "*/__pycache__/*",
]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "def __str__",
    "raise AssertionError",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
]
show_missing = true
precision = 2