Syncing with fork repository with Cursor AI help.

[gabrielborges-nimble]

Sync with upstream cleder/fastkml

This PR syncs this fork with the upstream repository https://github.com/cleder/fastkml while preserving critical local changes.

Overview

The upstream repository underwent a major refactoring that modernized the codebase with:

• Modern Python practices (type hints, better architecture)
• Improved class hierarchy and file organization
• Enhanced KML specification compliance
• Better error handling and validation

Changes Preserved

1. Garmin Device LineString Fix

File: fastkml/geometry.py
Issue: Garmin devices sometimes produce KML files with LineString elements containing only one coordinate tuple, which is technically invalid for a LineString.

Solution: Added validation in the LineString.geometry property to:

• Check if coordinates have fewer than 2 tuples
• Log a warning when invalid LineStrings are encountered
• Return None instead of crashing

def geometry(self) -> Optional[geo.LineString]:
    """Get the LineString geometry."""
    if not self.kml_coordinates:
        return None
    # issue seen with Garmin kml feeds with one coordinate linestrings
    if len(self.kml_coordinates.coords) < 2:
        logger.warning('LineStrings must have at least 2 coordinate tuples')
        return None
    try:
        return geo.LineString.from_coordinates(self.kml_coordinates.coords)
    except DimensionError:
        return None

2. NetworkLink and Link Classes

Status: ✅ Already covered by upstream
The upstream version includes comprehensive NetworkLink and Link implementations that are more feature-complete than the original local versions:

• NetworkLink (fastkml/features.py): Full KML specification support
• Link (fastkml/links.py): Complete implementation with refresh modes, view refresh modes, etc.
• NetworkLinkControl (fastkml/network_link_control.py): Additional network link control features

Testing

Added comprehensive unit tests for the Garmin fix in tests/geometries/linestring_test.py:

• test_garmin_single_coordinate_linestring(): Verifies single-coordinate LineStrings return None
• test_garmin_single_coordinate_linestring_with_warning(): Ensures warning is logged
• test_garmin_single_coordinate_linestring_from_string(): Tests XML parsing edge case
• test_garmin_single_coordinate_linestring_with_altitude(): Tests 3D coordinate edge case
• test_garmin_empty_coordinates(): Tests empty coordinates handling
• test_garmin_none_coordinates(): Tests None coordinates handling
• test_garmin_fix_preserves_existing_behavior(): Ensures fix doesn't break valid LineStrings

Migration Notes

API Changes

• KML.from_string(xml_string) → KML.parse(file)
• NetworkLink and Link classes moved to separate modules
• Registry-based parsing system

Benefits of Sync

1. Modern Codebase: Type hints, better error handling, improved architecture
2. Enhanced Features: More comprehensive KML specification support
3. Better Maintainability: Cleaner code structure and organization
4. Preserved Functionality: All critical local fixes maintained

Files Modified

• fastkml/geometry.py: Added Garmin LineString validation
• tests/geometries/linestring_test.py: Added comprehensive test coverage
• All other files: Synced with upstream (resolved merge conflicts)

Verification

The sync has been tested to ensure:

• ✅ Garmin single-coordinate LineStrings are handled gracefully
• ✅ Valid LineStrings continue to work normally
• ✅ NetworkLink functionality is preserved and enhanced
• ✅ All existing tests pass
• ✅ New tests provide comprehensive coverage

Contribution Ready

This sync makes the codebase ready for contributing the Garmin fix back to the upstream repository, as it:

• Maintains compatibility with the modern upstream codebase
• Includes comprehensive test coverage
• Follows upstream coding standards and patterns
• Preserves all critical functionality while gaining upstream improvements

[github-actions]

Failed to generate code suggestions for PR