feat[pmtiles]: support multiple shapes per routes

[davidgamez]

Summary:

This PR adds support for multiple shapes per route. No additional information has been added to the routes.json regarding shapes.

Expected behavior:

All shapes are represented in the pmtiles.

Left image, one shape per route. Right image, multiple shapes per route.

From our AI friend

This pull request introduces improvements to the GTFS CSV caching and GeoJSON conversion logic, focusing on safer data extraction, more robust handling of missing or malformed data, and enhanced support for routes with multiple shapes and trips. The most important changes are grouped below.

Data Extraction and Safety Improvements

• Added the get_safe_int helper for safely extracting integer values, and updated get_safe_value and get_safe_float to use explicit type hints for better type safety. [1] [2] [3] [4]
• Refactored code in gtfs_stops_to_geojson.py and main.py to consistently use get_safe_value and get_safe_float for extracting values from CSV rows, reducing the risk of exceptions and ensuring missing or malformed data is handled gracefully. [1] [2] [3] [4] [5] [6]

Route and Shape Handling Enhancements

• Redesigned the shape and trip mapping in CsvCache: get_shape_from_route now returns all shape IDs and their associated trips for a route, and added tracking of trips without shapes. This enables more accurate representation of GTFS data where multiple shapes or trips may exist per route. [1] [2] [3]
• Updated the route GeoJSON generation logic in main.py to support multiple shapes and trips per route. Each route feature now includes shape and trip information, and falls back to using stops when shape data is missing. [1] [2] [3]

Type Hints and Structure

• Introduced new TypedDicts (ShapeTrips, RouteCoordinates) and added type hints throughout the codebase for improved readability and static analysis. [1] [2] [3]

Dependency Updates

• Added new development dependencies (psutil, gcp_storage_emulator) to requirements_dev.txt for enhanced testing and local development.
  Testing tips:

Provide tips, procedures and sample files on how to test the feature.
Testers are invited to follow the tips AND to try anything they deem relevant outside the bounds of the testing tips.

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)

[Copilot]

Pull Request Overview

This PR refactors the PMTiles builder to support multiple route shapes by allowing routes to have multiple shape_ids with associated trip_ids. The main purpose is to handle cases where a single route can have different shapes for different trips.

• Transforms route-to-shape relationship from single shape_id to multiple shapes with trip associations
• Adds support for trips without shapes by falling back to stop coordinates
• Improves error handling and data validation using safe value getters

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
functions-python/pmtiles_builder/src/main.py	Core refactoring to support multiple route shapes with new RouteCoordinates type and get_route_coordinates method
functions-python/pmtiles_builder/src/csv_cache.py	Updates CsvCache to track multiple shapes per route and trips without shapes
functions-python/pmtiles_builder/src/gtfs_stops_to_geojson.py	Replaces direct row access with safe value getters for better data validation
functions-python/helpers/transform.py	Adds get_safe_int function and improves type hints for existing safe value functions
functions-python/helpers/tests/test_transform.py	Adds unit tests for the new get_safe_int function
functions-python/pmtiles_builder/src/scripts/pmtiles_builder_verifier.py	New verification script for testing PMTiles builder functionality
functions-python/pmtiles_builder/requirements_dev.txt	Adds development dependencies for testing and emulation

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[cka-y]

LGTM!

[jcpitre]

Great work!