feat(queries): implement coordinate order validation and UserWarnings for spatial queries (#66)

[angel-cm-dev]

🚀 Overview

This Pull Request addresses Issue #66 by implementing proactive validation for coordinate ordering in bounding_box and polygon methods within the GranuleQuery class.

The primary goal is to prevent common user errors—such as flipped latitude/longitude pairs—that lead to unintentional antimeridian crossings or empty API results. By providing immediate feedback via UserWarning, we improve the developer experience and reduce unnecessary load on the CMR API.

✅ Key Changes

• Data Sanitization: Implemented explicit float() casting for all spatial parameters. This ensures type safety and prevents potential string-injection issues in the generated query parameters.
• Bounding Box Intelligence: Added logic to detect if lower_left_lon > upper_right_lon or if latitudes are flipped, triggering a UserWarning with clear descriptive feedback.
• Polygon Analysis: Added a check for the longitude span of polygons. If the span exceeds 180 degrees, a warning is issued to alert the user about possible coordinate flipping or intended antimeridian crossings.
• Code Standards: The code has been refactored to comply with PEP 8 standards using Ruff. Clean code principles (SOLID) were applied to keep the methods readable and maintainable.

🧪 Testing & Verification

I have performed rigorous testing to ensure the robustness of these changes:

1. Unit Testing: Created tests/test_issue_66.py utilizing unittest.TestCase.assertWarns. This verifies that warnings are triggered exactly when expected and silenced during valid queries.
2. Integration (NASA UAT): Manually verified the fix against the NASA CMR UAT environment (cmr.uat.earthdata.nasa.gov).
   • Verified that the generated URLs are correctly formatted (e.g., bounding_box=10.0,0.0,-10.0,5.0).
   • Confirmed the library gracefully handles empty results from the API after the warning is issued.
3. Environment: Tests were executed on Python 3.14.3 on Windows 11, ensuring compatibility with the latest Python releases.

🔗 Related Issues

Closes #66