Source code for shapelib.core.cloud.handlers.remote_kml_handler

"""Remote handler for KML files using download."""

import tempfile
from pathlib import Path
from typing import Any

import geopandas as gpd

from shapelib.core.cloud.handlers.remote_handler import RemoteGeoFileHandler
from shapelib.factories.cloud_registry import register_cloud_handler




@register_cloud_handler(".kml")
class RemoteKmlHandler(RemoteGeoFileHandler):
    """
    Handler for remote KML files using download.

    KML files have limited streaming support in GDAL, so this handler
    downloads the file before reading.

    Attributes
    ----------
    driver : str
        GDAL driver name: "KML".
    extension : str
        File extension: ".kml".

    Examples
    --------
    >>> from shapelib import read_file
    >>> points = read_file("https://example.com/data.kml")

    Big-O
    -----
    O(n) with full download required.
    """

    driver: str = "KML"
    extension: str = ".kml"



    def load_data(self, **kwargs: Any) -> gpd.GeoDataFrame:
        """
        Load KML data by downloading to temporary location.

        Parameters
        ----------
        **kwargs : Any
            Additional arguments passed to geopandas.read_file().

        Returns
        -------
        gpd.GeoDataFrame
            The loaded geospatial data.
        """
        from shapelib.factories.geo_cloud_factory import GeoCloudFactory

        with tempfile.TemporaryDirectory() as temp_dir:
            filename = Path(self.cloud_path.path).name
            temp_path = Path(temp_dir) / filename
            GeoCloudFactory.download_file(self.cloud_path, temp_path)
            return gpd.read_file(temp_path, **kwargs)