shapelib.factories package#

Submodules#

shapelib.factories.cloud_registry module#

Decorators for registering cloud components (handlers, providers, writers).

shapelib.factories.cloud_registry.register_cloud_handler(file_extension)[source]#

Decorator to register a remote file handler with GeoCloudFactory.

This decorator associates a file extension with a remote handler class, enabling GeoCloudFactory to automatically select the correct handler for remote files based on their extension.

Parameters:: file_extension (str) – The file extension this handler supports (e.g., “.fgb”, “.shp”).
Returns:: A decorator that registers the handler class.
Return type:: Callable[[type[Any]], type[Any]]

Examples

>>> @register_cloud_handler(".fgb")
... class RemoteFlatGeobufHandler(RemoteGeoFileHandler):
...     driver = "FlatGeobuf"
...     extension = ".fgb"
...
...     def load_data(self, **kwargs):
...         return gpd.read_file(self.cloud_path.vsicurl_path, **kwargs)

shapelib.factories.cloud_registry.register_cloud_provider(cls)[source]#

Decorator to register a cloud provider with GeoCloudFactory.

This decorator registers a cloud provider class (S3, HTTPS, GCS, etc.) enabling GeoCloudFactory to automatically select the correct provider for cloud operations based on the URL scheme.

Parameters:: cls (type[Any]) – The provider class to register.
Returns:: The registered provider class.
Return type:: type[Any]

Examples

>>> @register_cloud_provider
... class S3Provider:
...     def supports(self, cloud_path: CloudPath) -> bool:
...         return cloud_path.is_s3_protocol
...
...     def upload(self, source: Path, cloud_path: CloudPath) -> None:
...         # S3 upload logic
...         ...

shapelib.factories.cloud_registry.register_cloud_writer(cls)[source]#

Decorator to register a cloud writer with BaseShapes.

This decorator registers a writer class for cloud file operations, enabling BaseShapes.save() to automatically select the correct writer based on the file format and destination.

Parameters:: cls (type[Any]) – The writer class to register.
Returns:: The registered writer class.
Return type:: type[Any]

Examples

>>> @register_cloud_writer
... class FlatGeobufCloudWriter(BaseCloudWriter):
...     def supports(self, cloud_path: CloudPath) -> bool:
...         return cloud_path.is_remote and cloud_path.extension == ".fgb"
...
...     def _build_write_kwargs(self, ...) -> dict:
...         return {"engine": "pyogrio", ...}

shapelib.factories.geo_cloud_factory module#

Factory for handling remote geospatial files from cloud storage.

class shapelib.factories.geo_cloud_factory.GeoCloudFactory[source]#

Bases: object

Factory for creating handlers for remote geospatial files.

This class mirrors GeoFileFactory’s architecture but for remote files. It maintains a registry of handlers for different file formats and a registry of providers for different cloud protocols.

Each handler knows whether to use streaming (vsicurl) or download for its specific format. Each provider handles upload/download for its specific protocol.

Variables:

_handlers (dict[str, type[RemoteGeoFileHandler]]) – Registry mapping file extensions to handler classes.
_providers (list[CloudProvider]) – Registry of cloud providers (S3, HTTPS, etc.).

Examples

Read a remote FlatGeobuf file:

>>> geometry = GeoCloudFactory.get_handler(
...     "https://bucket.s3.amazonaws.com/file.fgb?signature=..."
... )
>>> print(type(geometry))
<class 'shapelib.core.geometries.lines.Lines'>

Big-O

O(n) for streaming formats, O(n) + disk I/O for download formats.

classmethod register_handler(file_extension, handler_class)[source]#

Register a handler for a specific file extension.

Parameters:

file_extension (str) – The file extension (e.g., “.fgb”, “.shp”).
handler_class (type[RemoteGeoFileHandler]) – The handler class for this extension.

Return type:

None

classmethod register_provider(provider)[source]#

Register a cloud provider.

Providers are checked in registration order (last registered = first checked).

Parameters:: provider (CloudProvider) – The provider instance to register.
Return type:: None

classmethod get_provider(cloud_path)[source]#

Get the appropriate provider for a cloud path.

Parameters:: cloud_path (CloudPath) – The parsed cloud path.
Returns:: The provider that supports this path.
Return type:: CloudProvider
Raises:: ValueError – If no provider supports this path.

classmethod get_handler(path, keep_z=False, **kwargs)[source]#

Get the appropriate handler and create geometry from remote file.

Parameters:

path (str) – The remote URL to the geospatial file.
keep_z (bool) – Keep the Z coordinate of 3-D geometries (default False). Handed to the handler, never to the file reader underneath it.
**kwargs (Any) – Additional arguments passed to the handler.

Returns:

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

Return type:

BaseShapes

Raises:

ValueError – If no handler is registered for the file extension.
ConnectionError – If the remote file cannot be accessed.
FileNotFoundError – If the remote file does not exist.

classmethod upload_file(source, destination)[source]#

Upload a local file to cloud storage.

Parameters:

source (Path) – The local file to upload.
destination (str) – The remote URL destination (presigned PUT URL or s3://).

Raises:

FileNotFoundError – If the source file does not exist.
ConnectionError – If the upload fails.
PermissionError – If access is denied.
ValueError – If no provider supports the destination protocol.

Return type:

None

classmethod download_file(cloud_path, destination)[source]#

Download a remote file to local destination.

Used internally by download-based handlers.

Parameters:

cloud_path (CloudPath) – The remote source path.
destination (Path) – The local destination path.

Returns:

The path to the downloaded file.

Return type:

Path

Raises:

FileNotFoundError – If the remote file does not exist.
ConnectionError – If the download fails.
PermissionError – If access is denied.
ValueError – If no provider supports the source protocol.

classmethod file_exists(cloud_path)[source]#

Check if a remote file exists without downloading.

Parameters:: cloud_path (CloudPath) – The remote file path to check.
Returns:: True if the file exists, False otherwise.
Return type:: bool

shapelib.factories.geo_file_factory module#

class shapelib.factories.geo_file_factory.GeoFileFactory[source]#

Bases: object

A factory class for creating file handlers for geospatial files.

This class is responsible for registering handlers for different file formats and retrieving the appropriate handler based on a file’s extension.

Variables:

_handlers (dict) – A dictionary that maps file extensions (e.g., “.shp”, “.geojson”) to their corresponding handler classes.

Methods:

register_handler(file_extension, handler_class) – Registers a new handler class for a specific file extension.
get_handler(path) – Retrieves the appropriate file handler for the given file path based on its extension.

classmethod register_handler(file_extension, handler_class)[source]#

Register a handler for a specific file extension.

This method associates a file extension (e.g., “.shp”, “.geojson”) with a handler class. When a file with the registered extension is processed, the corresponding handler class will be used.

Parameters:

file_extension (str) – The file extension that the handler class is responsible for (e.g., “.shp”).
handler_class (type[GeoFileHandler]) – The handler class to be registered for the specified file extension.

Returns:

The method registers the handler in the _handlers dictionary.

Return type:

None

Examples

>>> GeoFileFactory.register_handler(".shp", ShapefileHandler)
Adding support for .shp files through ShapefileHandler

classmethod get_handler(path, keep_z=False, **kwargs)[source]#

Retrieve the appropriate file handler for the given file path based on its extension.

This method determines the file extension of the provided path and retrieves the corresponding handler class. If a handler for the file extension is found, the method creates an instance of the handler and returns it.

Parameters:

path (Path) – The path to the geospatial file.
keep_z (bool) – Keep the Z coordinate of 3-D geometries (default False). Handed to the handler, never to the file reader underneath it.
**kwargs (Any) – Additional arguments passed to the handler’s reader.

Returns:

An instance of the appropriate handler for the file.

Return type:

BaseShapes

Raises:

ValueError – If the file extension does not have a registered handler.

Examples

>>> handler = GeoFileFactory.get_handler(Path("/path/to/file.shp"))
>>> handler.create_obj()  # Creates an object based on the shapefile's data.

shapelib.factories.registry module#

shapelib.factories.registry.register_handler(file_extension)[source]#

A decorator to register a geospatial file handler class with the GeoFileFactory.

This decorator function associates a file extension (e.g., “.shp”, “.geojson”) with a handler class in the GeoFileFactory. The handler class is registered to process files with the specified extension.

Parameters:: file_extension (str) – The file extension that the handler class can process (e.g., “.shp”).
Returns:: A decorator function that registers the handler class with GeoFileFactory.
Return type:: Callable[[type[Any]], type[Any]]

Examples

>>> @register_handler(".shp")
>>> class ShapefileHandler(GeoFileHandler):
>>>     # Class implementation here
>>>     pass