feat(ogc): add opt-in parallel chunk fan-out

[thodson-usgs]

Summary

• Add parallel_chunks(n) for opt-in fan-out of large Water Data and NGWMN requests.
• Preserve conservative byte-limit chunking by default and cap optional fan-out across all chunk axes.
• Document quota, max_rows, retry/resume tradeoffs and add planner/integration coverage.

Basic usage

from dataretrieval import waterdata

sites, _ = waterdata.get_monitoring_locations(
    state="Ohio",
    site_type_code="ST",
)

with waterdata.parallel_chunks(32):
    df, metadata = waterdata.get_daily(
        monitoring_location_id=sites["monitoring_location_id"],
        parameter_code="00060",
        time="2004-01-01/2023-12-31",
    )

Use this only for large, paginated pulls with a multi-value argument. Each sub-request consumes quota; concurrent execution remains bounded separately by API_USGS_CONCURRENT (default 32).

Timing

Fixed 271-site Ohio stream-gage subset, get_daily(parameter_code="00060"), limit=250; each run used a cold one-year window.

n	Parallelism	Pages	Wall-clock	Speedup
off	1	~30	9.5 s / 9.1 s	1×
8	8	~32	2.2 s / 1.9 s	~4.5×
32	32	54	1.2 s	~8×

Validation

• pytest -q tests/waterdata_chunking_test.py tests/utils_test.py
• ruff check on changed Python files
• 89,600 generated multi-axis plan checks