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

"""Remote handler for GeoPackage files using download strategy."""

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(".gpkg")
class RemoteGeopackageHandler(RemoteGeoFileHandler):
    """
    Handler for remote GeoPackage files using download strategy.

    GeoPackage is SQLite-based which requires random access to the file.
    GDAL's /vsis3/ virtual filesystem has limited support for SQLite files,
    so this handler downloads the file first for reliable operation.
    For streaming support, consider using FlatGeobuf format instead.

    Attributes
    ----------
    driver : str
        GDAL driver name: "GPKG".
    extension : str
        File extension: ".gpkg".

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

    Big-O
    -----
    O(n) where n is file size (full download required).
    """

    driver: str = "GPKG"
    extension: str = ".gpkg"



    def load_data(self, **kwargs: Any) -> gpd.GeoDataFrame:
        """
        Load GeoPackage data by downloading first.

        Parameters
        ----------
        **kwargs : Any
            Additional arguments, including 'layer' for multi-layer files.

        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
            local_path = Path(temp_dir) / filename
            GeoCloudFactory.download_file(self.cloud_path, local_path)
            return gpd.read_file(local_path, **kwargs)