shapelib.core.cloud.handlers package#

Remote file handlers for cloud storage.

Handlers are registered with GeoCloudFactory via @register_cloud_handler decorator. Import this module to trigger handler registration.

Submodules#

shapelib.core.cloud.handlers.remote_flatgeobuf_handler module#

Remote handler for FlatGeobuf files using streaming.

class shapelib.core.cloud.handlers.remote_flatgeobuf_handler.RemoteFlatGeobufHandler(cloud_path)[source]#

Bases: RemoteGeoFileHandler

Handler for remote FlatGeobuf files using GDAL streaming.

FlatGeobuf is optimized for streaming with HTTP range request support, making it ideal for cloud storage. This handler uses GDAL’s /vsicurl/ to read data directly without downloading the entire file.

Variables:

driver (str) – GDAL driver name: “FlatGeobuf”.
extension (str) – File extension: “.fgb”.

Parameters:

cloud_path (CloudPath)

Examples

>>> from shapelib import read_file
>>> lines = read_file("https://bucket.s3.amazonaws.com/file.fgb")
>>> print(type(lines))
<class 'shapelib.core.geometries.lines.Lines'>

Big-O

O(n) with efficient range requests - no full download required.

driver: str = 'FlatGeobuf'#

extension: str = '.fgb'#

load_data(**kwargs)[source]#

Load FlatGeobuf data via GDAL streaming.

Parameters:

**kwargs (Any) – Additional arguments passed to geopandas.read_file().

Returns:

The loaded geospatial data.

Return type:

GeoDataFrame

Raises:

ConnectionError – If the remote file cannot be accessed.
FileNotFoundError – If the remote file does not exist.

shapelib.core.cloud.handlers.remote_geojson_handler module#

Remote handler for GeoJSON files using streaming.

class shapelib.core.cloud.handlers.remote_geojson_handler.RemoteGeojsonHandler(cloud_path)[source]#

Bases: RemoteGeoFileHandler

Handler for remote GeoJSON files using GDAL streaming.

GeoJSON files can be read via streaming, though the entire JSON structure typically needs to be parsed. For very large files, consider using FlatGeobuf instead.

Variables:

driver (str) – GDAL driver name: “GeoJSON”.
extension (str) – File extension: “.geojson” or “.json”.

Parameters:

cloud_path (CloudPath)

Examples

>>> from shapelib import read_file
>>> polygons = read_file("https://example.com/data.geojson")

Big-O

O(n) - full file read required for JSON parsing.

driver: str = 'GeoJSON'#

extension: str = '.geojson'#

load_data(**kwargs)[source]#

Load GeoJSON data via GDAL streaming.

Parameters:: **kwargs (Any) – Additional arguments passed to geopandas.read_file().
Returns:: The loaded geospatial data.
Return type:: GeoDataFrame

shapelib.core.cloud.handlers.remote_geopackage_handler module#

Remote handler for GeoPackage files using download strategy.

class shapelib.core.cloud.handlers.remote_geopackage_handler.RemoteGeopackageHandler(cloud_path)[source]#

Bases: 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.

Variables:

driver (str) – GDAL driver name: “GPKG”.
extension (str) – File extension: “.gpkg”.

Parameters:

cloud_path (CloudPath)

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'#

load_data(**kwargs)[source]#

Load GeoPackage data by downloading first.

Parameters:: **kwargs (Any) – Additional arguments, including ‘layer’ for multi-layer files.
Returns:: The loaded geospatial data.
Return type:: GeoDataFrame

shapelib.core.cloud.handlers.remote_handler module#

Abstract base class for remote geospatial file handlers.

class shapelib.core.cloud.handlers.remote_handler.RemoteGeoFileHandler(cloud_path)[source]#

Bases: ABC

Abstract base class for handling remote geospatial files.

This class defines the interface for remote file handlers. Each handler knows how to read its specific format from remote storage, either via streaming (GDAL virtual filesystem) or download.

Subclasses must implement load_data() to define how data is retrieved from the remote source.

Variables:

driver (str) – The GDAL driver name for the format.
extension (str) – The file extension this handler supports.
keep_z (bool) – Whether the object created from the file keeps the Z coordinate of 3-D geometries. False by default; set by the factory from read_file.

Parameters:

cloud_path (CloudPath) – The remote path to the file.

Examples

Creating a custom remote handler:

>>> @register_cloud_handler(".myformat")
... class RemoteMyFormatHandler(RemoteGeoFileHandler):
...     driver = "MyFormat"
...     extension = ".myformat"
...
...     def load_data(self, **kwargs) -> gpd.GeoDataFrame:
...         return gpd.read_file(self.cloud_path.vsicurl_path, **kwargs)

driver: str = ''#

extension: str = ''#

keep_z: bool = False#

create_obj(**kwargs)[source]#

Load data and create the appropriate geometry object.

Parameters:

**kwargs (Any) – Additional arguments passed to load_data().

Returns:

The geometry object (Polygons, Lines, Points, or Empty).

Return type:

BaseShapes

Raises:

ConnectionError – If the remote file cannot be accessed.
FileNotFoundError – If the remote file does not exist.

abstractmethod load_data(**kwargs)[source]#

Load data from the remote source.

Subclasses implement this to define how data is retrieved: - Streaming handlers use GDAL’s vsicurl/vsis3 - Download handlers fetch to temp and delegate to local handlers

Parameters:

**kwargs (Any) – Additional arguments (e.g., layer name for GeoPackage).

Returns:

The loaded geospatial data.

Return type:

GeoDataFrame

Raises:

ConnectionError – If the remote file cannot be accessed.
FileNotFoundError – If the remote file does not exist.

shapelib.core.cloud.handlers.remote_kml_handler module#

Remote handler for KML files using download.

class shapelib.core.cloud.handlers.remote_kml_handler.RemoteKmlHandler(cloud_path)[source]#

Bases: RemoteGeoFileHandler

Handler for remote KML files using download.

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

Variables:

driver (str) – GDAL driver name: “KML”.
extension (str) – File extension: “.kml”.

Parameters:

cloud_path (CloudPath)

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'#

load_data(**kwargs)[source]#

Load KML data by downloading to temporary location.

Parameters:: **kwargs (Any) – Additional arguments passed to geopandas.read_file().
Returns:: The loaded geospatial data.
Return type:: GeoDataFrame

shapelib.core.cloud.handlers.remote_shapefile_handler module#

Remote handler for Shapefile files using download.

class shapelib.core.cloud.handlers.remote_shapefile_handler.RemoteShapefileHandler(cloud_path)[source]#

Bases: RemoteGeoFileHandler

Handler for remote Shapefile files using download.

Shapefiles require multiple component files (.shp, .shx, .dbf, .prj, .cpg). This handler downloads all sidecar files to a temporary directory before reading.

Note: For cloud storage, FlatGeobuf or GeoPackage are recommended as they are single-file formats with streaming support.

Variables:

driver (str) – GDAL driver name: “ESRI Shapefile”.
extension (str) – File extension: “.shp”.
sidecar_extensions (tuple[str, ]) – Required and optional sidecar file extensions.

Parameters:

cloud_path (CloudPath)

Examples

>>> from shapelib import read_file
>>> polygons = read_file("https://example.com/data.shp")

Big-O

O(n) with full download of all component files required.

driver: str = 'ESRI Shapefile'#

extension: str = '.shp'#

sidecar_extensions: tuple[str, ...] = ('.shx', '.dbf', '.prj', '.cpg')#

load_data(**kwargs)[source]#

Load Shapefile data by downloading all component files.

Downloads .shp and all sidecar files (.shx, .dbf, .prj, .cpg) to a temporary directory before reading.

For s3:// URLs, sidecar files are downloaded automatically. For HTTPS presigned URLs, each sidecar needs its own presigned URL, so this may fail. Use s3:// protocol or FlatGeobuf format instead.

Parameters:: **kwargs (Any) – Additional arguments passed to geopandas.read_file().
Returns:: The loaded geospatial data.
Return type:: GeoDataFrame

shapelib.core.cloud.handlers.remote_spatialite_handler module#

Remote handler for SpatiaLite files using download.

class shapelib.core.cloud.handlers.remote_spatialite_handler.RemoteSpatialiteHandler(cloud_path)[source]#

Bases: RemoteGeoFileHandler

Handler for remote SpatiaLite files using download.

SpatiaLite (SQLite-based) requires full file access for proper operation, so this handler downloads the file before reading.

Variables:

driver (str) – GDAL driver name: “SQLite”.
extension (str) – File extension: “.sqlite”.

Parameters:

cloud_path (CloudPath)

Examples

>>> from shapelib import read_file
>>> polygons = read_file("https://example.com/data.sqlite", layer="regions")

Big-O

O(n) with full download required.

driver: str = 'SQLite'#

extension: str = '.sqlite'#

load_data(**kwargs)[source]#

Load SpatiaLite data by downloading to temporary location.

Parameters:: **kwargs (Any) – Additional arguments, including ‘layer’ for multi-layer files.
Returns:: The loaded geospatial data.
Return type:: GeoDataFrame