fix: add bounds selection support

[0xSwego]

Summary by CodeRabbit

• New Features

  • Single-call dataset selection that accepts rectangular bounds and time ranges
  • Flexible geographic selection using custom latitude/longitude field names
  • Unified method to apply geographic and temporal filters in one operation

• Documentation

  • README updated with a Python example demonstrating the new select workflow

• Tests

  • Added tests covering bounds/selection behavior and the new single-call selection

• Chores

  • Package version bumped to 0.5.8

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bf7a7853-35cc-446a-bd15-a995194d8569

📥 Commits

Reviewing files that changed from the base of the PR and between f72f0c5 and a5b23d4.

📒 Files selected for processing (3)

• dclimate_client_py/client.py
• dclimate_client_py/dclimate_client.py
• tests/test_geotemporal_data.py

🚧 Files skipped from review as they are similar to previous changes (2)

• tests/test_geotemporal_data.py
• dclimate_client_py/client.py

---

📝 Walkthrough

Walkthrough

This PR extends the dClimate Python client with bounds-based geospatial filtering and coordinate key customization. It adds a unified selection API (GeotemporalData.select), configurable coordinate keys for point/rectangle, and a client convenience method (select_dataset) that loads and applies spatial/temporal selection in one call.

Changes

Unified Geospatial Selection Interface

Layer / File(s)	Summary
Selection type contracts and helper functions dclimate_client_py/geotemporal_data.py	Type aliases BoundsSelection and GeoSelectionOptions and internal helpers validate and normalize selection mappings, numeric bounds, points, time ranges, and coordinate option keys.
Flexible coordinate key support in point and rectangle dclimate_client_py/geotemporal_data.py	point and rectangle methods accept latitude_key and longitude_key (defaults "latitude"/"longitude"), resolve coordinate arrays by those keys, and use them for selections or bounds filtering.
GeotemporalData.select unified selection method dclimate_client_py/geotemporal_data.py	New select(selection) validates mapping inputs, enforces mutual exclusivity of point/bounds, optionally applies time_range, normalizes parameters, and dispatches to point, rectangle, and time_range.
Query method bounds parameter and routing dclimate_client_py/geotemporal_data.py	GeotemporalData.query adds bounds: BoundsSelection and bounds_options: dict and routes normalized bounds (with coordinate overrides) to rectangle.
Client-level geo_temporal_query bounds support dclimate_client_py/client.py	geo_temporal_query adds bounds and bounds_options to its signature and docstring, includes bounds in the geographic selector conflict check, and forwards them to data.query(...).
dClimateClient.select_dataset convenience wrapper dclimate_client_py/dclimate_client.py	New async select_dataset(request, selection, return_xarray=False) validates request/selection as mappings, normalizes load_dataset args (coercing dataset when only cid provided), calls load_dataset, and applies GeotemporalData.select(selection) if applicable.
Selection and bounds tests tests/test_geotemporal_data.py	Adds tests for custom coordinate-key rectangle/select behavior, bounds+time_range selection, object-form bounds with key overrides, validation errors, and async tests verifying select_dataset forwarding and returned selection/metadata.
README example and version bump README.md, pyproject.toml	Adds a README usage snippet demonstrating select_dataset with request and selection payloads; bumps package version 0.5.7 → 0.5.8.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I sniffed the bounds and found their lore,
Keys unlatched so lat/lon explore,
One map, one call — the dataset sings,
Time and region folded into wings,
Hoppity hops for selection things.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: add bounds selection support' directly and concisely describes the main feature addition across multiple files enabling rectangular geographic bounds filtering.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bounds-selection

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

dclimate_client_py/client.py (1)

69-71: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Update exclusivity docs to include bounds.

The mutual-exclusivity sentence is stale after adding bounds support, so the docs now contradict runtime behavior.

Suggested doc fix

-    Only one of point, circle, rectangle, or polygon kwargs may be provided. Only one of
+    Only one of point, circle, rectangle, bounds, or polygon kwargs may be provided. Only one of

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dclimate_client_py/client.py` around lines 69 - 71, The exclusivity docstring
sentence that currently reads "Only one of point, circle, rectangle, or polygon
kwargs may be provided..." is stale after adding bounds support; update that
sentence to include bounds (e.g., "Only one of point, circle, rectangle,
polygon, or bounds kwargs may be provided.") while keeping the following clause
about temporal vs rolling aggregations unchanged; locate and edit the same
docstring text in client.py where the spatial/temporal exclusivity is described.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@dclimate_client_py/dclimate_client.py`:
- Around line 364-371: The call to self.load_dataset is passing return_xarray
both from the explicit return_xarray parameter and possibly inside load_kwargs
built from request, causing a TypeError; before calling self.load_dataset (in
the select_dataset flow where load_kwargs is created), remove any
'return_xarray' entry from load_kwargs (e.g., load_kwargs.pop("return_xarray",
None)) so the explicit return_xarray argument is the only one passed to
self.load_dataset and avoid duplicate keyword errors.

---

Outside diff comments:
In `@dclimate_client_py/client.py`:
- Around line 69-71: The exclusivity docstring sentence that currently reads
"Only one of point, circle, rectangle, or polygon kwargs may be provided..." is
stale after adding bounds support; update that sentence to include bounds (e.g.,
"Only one of point, circle, rectangle, polygon, or bounds kwargs may be
provided.") while keeping the following clause about temporal vs rolling
aggregations unchanged; locate and edit the same docstring text in client.py
where the spatial/temporal exclusivity is described.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 061ef4fc-9446-4665-964f-4a48e4c590e9

📥 Commits

Reviewing files that changed from the base of the PR and between 652346b and f72f0c5.

📒 Files selected for processing (6)

• README.md
• dclimate_client_py/client.py
• dclimate_client_py/dclimate_client.py
• dclimate_client_py/geotemporal_data.py
• pyproject.toml
• tests/test_geotemporal_data.py

[Faolain]

Handled the CodeRabbit outside-diff docstring comment in a5b23d4: geo_temporal_query now documents that only one of point, circle, rectangle, bounds, or polygon may be provided.

Validation: .venv/bin/ruff check dclimate_client_py/dclimate_client.py dclimate_client_py/client.py tests/test_geotemporal_data.py, compileall, and tests/test_geotemporal_data.py all pass locally.