Caching improvements

[jm-rivera]

This pull request introduces major improvements to how oda_data manages its caching system, providing a more robust, user-friendly, and transparent cache management experience. The cache is now stored in a standard per-user, per-version directory, with a unified API for inspecting, clearing, and migrating cache data. Existing caches are automatically migrated on first use, and new documentation thoroughly explains all cache operations, recovery, and migration scenarios.

Key changes include:

New cache system and user API

• Introduced a detailed CACHING.md guide documenting the new cache system, including cache locations, configuration, Python API (oda_data.cache), migration from older versions, recovery from corrupt cache, and multi-process behavior. The document also covers legacy compatibility for standalone oda_reader users.
• Added a new oda_data.cache namespace, providing type-safe, granular cache management functions (size, clear, invalidate, enable_cache, disable_cache, migrate, etc.) and allowing per-scope operations for advanced workflows.
• The cache now defaults to a per-user, per-version directory determined by the OS, with override capability via set_cache_root() or the ODA_DATA_CACHE_DIR environment variable. [1] [2]

Documentation and user guidance

• Updated the main README.md to describe the new cache behavior, including how to recover from corrupt caches and the relationship between legacy helpers and the new API.
• Added and updated changelogs (CHANGELOG.md, docs/docs/changelog.md) with detailed release notes for version 2.6.0, summarizing the new cache system, migration process, API changes, and backward compatibility. [1] [2]

Backward compatibility and migration

• Existing cache management helpers (clear_cache, enable_cache, disable_cache) are preserved as thin wrappers over the new API, ensuring seamless upgrades for existing scripts. [1] [2] [3]
• Automatic migration of caches from pre-2.6 locations to the new layout, with clear logging and manual override for special cases (e.g., synced drives, disk full). [1] [2] [3]

These changes significantly improve cache reliability, transparency, and user control, making cache management easier and safer for all oda_data users.

References: [1] [2] [3] [4]

[codecov-commenter]

Codecov Report

❌ Patch coverage is 82.58528% with 97 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@dd001ba). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/oda_data/cache/api.py	86.51%	22 Missing and 7 partials ⚠️
src/oda_data/api/sources.py	45.65%	22 Missing and 3 partials ⚠️
src/oda_data/tools/cache.py	82.97%	13 Missing and 3 partials ⚠️
src/oda_data/cache/_migrate.py	86.79%	9 Missing and 5 partials ⚠️
src/oda_data/__init__.py	47.05%	9 Missing ⚠️
src/oda_data/cache/config.py	90.90%	3 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #159   +/-   ##
=======================================
  Coverage        ?   77.05%           
=======================================
  Files           ?       41           
  Lines           ?     2628           
  Branches        ?      265           
=======================================
  Hits            ?     2025           
  Misses          ?      550           
  Partials        ?       53           

Flag	Coverage Δ
unittests	77.05% <82.58%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.