Docs improvements

[jm-rivera]

This pull request focuses on improving the documentation for ODA Reader, clarifying usage instructions, updating schema/version fallback examples, and streamlining advanced usage and performance guidance. It also includes a new changelog entry for version 1.3.1, reflecting improved cache management and documentation. The most significant changes are grouped below.

Documentation Updates and Clarifications

• Updated advanced usage documentation to show version fallback now decrements from 1.5 instead of 1.0, and revised code examples accordingly. Also removed sections on custom schema handling and memory-efficient aggregation to streamline the guide. [1] [2] [3] [4] [5]
• Improved dataset documentation for clarity and conciseness, including more focused descriptions of dataset use cases and key dimensions, and refined guidance for AidData and DAC2a. [1] [2] [3] [4] [5] [6] [7]
• Clarified filtering documentation by specifying which codes to use for API calls versus returned data, and improved explanations of available filter dimensions for each dataset. [1] [2] [3] [4]

Performance and Bulk Download Guidance

• Removed performance comparison tables and combining bulk/API download examples from the bulk downloads documentation, and emphasized iterator-based memory-efficient processing. [1] [2]

Installation and Usage Instructions

• Updated installation instructions to use uv add oda-reader instead of uv pip install oda-reader for clarity.
• Clarified rate limiting documentation to specify a 20 requests per hour limit (was per 60 seconds), and simplified troubleshooting guidance.

General and Schema Translation Improvements

• Revised project introduction and feature list for clarity, and improved explanations of version fallback and schema translation in the main index and schema translation documentation. Also updated code tables to consistently show .Stat code first, and removed misleading comments about code human-readability. [1] [2] [3] [4] [5] [6]

Changelog

• Added a new entry for version 1.3.1 (2025-06-27), highlighting improved cache management, new tests, and documentation improvements.

[chatgpt-codex-connector]

💡 Codex Review

oda_reader/src/oda_reader/_cache/config.py

Lines 12 to 14 in 406c23c

	# Version for cache versioning (hardcoded to avoid circular import)
	# This should match the version in __init__.py
	__version__ = "1.3.0"

Update cache version constant to match 1.3.1

The package version was bumped to 1.3.1 in pyproject.toml, but __version__ in the cache configuration remains hardcoded to "1.3.0". get_cache_dir() incorporates this string into the cache path to force invalidation on upgrades. Leaving it at 1.3.0 means users installing 1.3.1 will continue using the old ~/.cache/oda-reader/1.3.0/ directory, so stale HTTP/DataFrame caches persist and the new filesystem cache backend introduced here won’t be isolated from the previous release.

---

oda_reader/src/oda_reader/common.py

Lines 115 to 118 in 406c23c

	def __init__(self, max_calls: int = 20, period: float = 60.0) -> None:
	self.max_calls = max_calls
	self.period = period
	self._calls: deque[float] = deque()

Adjust default rate limiter to 20 requests/hour

The updated documentation now states the client limits to 20 requests per hour, but the code still initializes RateLimiter with max_calls=20 in a 60‑second period and the global API_RATE_LIMITER uses those defaults. With no change here the library continues to allow up to 1200 calls per hour, which will violate a 20/hour API quota and trigger rate-limit errors. Either the constructor defaults or the docs need to be updated so throttling matches the documented limit.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".