feat: add reverse geolocation strategy parameter

[davidgamez]

Summary:
This PR adds the strategy parameter to the reverse geolocation processor. The only strategy supported currently is per-point. This is the already implemented algorithm that performs one reverse geolocation per geopositional point.
Minor changes:

• Added track_metrics annotation to log performance-related metrics
• Added a reverse geolocation verifier to perform local integration testing

Part of #1301

Expected behavior:

After this refactoring, the reverse geolocation should continue to work as it with no changes in the process.

From our AI friend

This pull request introduces several enhancements and refactorings to the reverse geolocation processing pipeline, focusing on improved configurability, extensibility, and observability. The main updates include the addition of a configurable reverse geocoding strategy, support for specifying the public/private status of output files, a new runtime metrics tracking decorator, and codebase refactoring for clarity and maintainability.

Configurability and Feature Additions:

• Added a ReverseGeocodingStrategy enum and support for specifying the strategy (currently only per-point) in both the request and processing logic, making the reverse geolocation process more extensible. (functions-python/helpers/locations.py, functions-python/reverse_geolocation/src/parse_request.py, functions-python/reverse_geolocation/src/reverse_geolocation_processor.py) [1] [2] [3] [4] [5] [6] [7]
• Added support for a public parameter in requests, allowing control over whether generated GeoJSON files are public or private. (functions-python/reverse_geolocation/README.md, functions-python/reverse_geolocation/src/parse_request.py, functions-python/reverse_geolocation/src/reverse_geolocation_processor.py) [1] [2] [3] [4]

Observability and Utility Improvements:

• Introduced a track_metrics decorator to monitor time, memory, and CPU usage for key functions, improving runtime observability and debugging. (functions-python/helpers/runtime_metrics.py, [1] [2] [3]
• Enhanced the to_boolean utility for more robust type conversion and added a generic to_enum utility for safely converting values to enum members. (functions-python/helpers/transform.py) [1] [2]

Refactoring and Documentation:

• Refactored the main reverse geolocation processing logic to use the new strategy pattern, clarified function names, and improved docstrings and example request documentation for better maintainability and clarity. (functions-python/reverse_geolocation/src/reverse_geolocation_processor.py, functions-python/reverse_geolocation/src/parse_request.py) [1] [2] [3]
• Updated test and coverage configuration and requirements to include new dependencies and ensure proper coverage of helper and script files. (functions-python/reverse_geolocation/.coveragerc, functions-python/reverse_geolocation/requirements.txt, functions-python/reverse_geolocation/requirements_dev.txt) [1] [2] [3]

Testing tips:

Local testing

• Use the reverse_geolocation_process_verifier.py for local testing

Please make sure these boxes are checked before submitting your pull request - thanks!

• Run the unit tests with ./scripts/api-tests.sh to make sure you didn't break anything
• Add or update any needed documentation to the repo
• Format the title like "feat: [new feature short description]". Title must follow the Conventional Commit Specification(https://www.conventionalcommits.org/en/v1.0.0/).
• Linked all relevant issues
• Include screenshot(s) showing how this pull request works and fixes the issue(s)

[jcpitre]

I'm a bit confused. It says here that we can pass a logger to the decorator, but in the code it uses the logger in the decorated function arguments. Maybe I'm misreading?

[davidgamez]

Sorry, that was the first implementation, but I had issues using the logger as a parameter, so I removed it. Now I took out the documentation.

[jcpitre]

Nitpick: Maybe stopfs_df should be renamed unmatched_stops_df to correspond to the name of the returned value from get_cached_geopolygons and to distinguish it from the original stops_df.

[jcpitre]

Great addition for tracking metrics!