shapelib.core.cloud.writers package#

Cloud file writers for remote storage.

Writers are auto-registered via @register_cloud_writer decorator. Import order matters: since register_writer() uses insert(0, …), later imports end up at position 0 (checked first).

Import order: Generic first (fallback), then specific writers (priority).

Submodules#

shapelib.core.cloud.writers.base_cloud_writer module#

Base class for cloud file writers.

class shapelib.core.cloud.writers.base_cloud_writer.BaseCloudWriter[source]#

Bases: ABC

Abstract base class for cloud file writers.

Each concrete writer handles a specific file format with format-specific optimizations for cloud storage.

Subclasses must implement: - supports(): Check if this writer handles the given path - _build_write_kwargs(): Build format-specific kwargs

Examples

>>> class MyFormatWriter(BaseCloudWriter):
...     def supports(self, cloud_path: CloudPath) -> bool:
...         return cloud_path.extension == ".myformat"
...
...     def _build_write_kwargs(self, ...) -> dict[str, Any]:
...         return {"driver": "MyFormat", **kwargs}

abstractmethod supports(cloud_path)[source]#

Check if this writer supports the given path.

Parameters:: cloud_path (CloudPath) – The parsed destination path.
Returns:: True if this writer handles the format.
Return type:: bool

write(gdf, cloud_path, driver=None, schema=None, index=None, **kwargs)[source]#

Write GeoDataFrame to cloud storage.

Parameters:

gdf (GeoDataFrame) – The GeoDataFrame to save.
cloud_path (CloudPath) – The remote destination path.
driver (str | None) – The file driver.
schema (Any | None) – The schema definition.
index (Any | None) – Whether to write the index.
**kwargs (Any) – Additional arguments passed to to_file().

Raises:

ConnectionError – If the upload fails.
PermissionError – If access is denied.

Return type:

None

shapelib.core.cloud.writers.flatgeobuf_cloud_writer module#

Cloud writer for FlatGeobuf files with streaming optimizations.

class shapelib.core.cloud.writers.flatgeobuf_cloud_writer.FlatGeobufCloudWriter[source]#

Bases: BaseCloudWriter

Cloud writer for FlatGeobuf files with streaming optimizations.

Applies cloud-optimized settings for FlatGeobuf uploads: - engine=”pyogrio”: Faster I/O engine - index=False: Skip pandas index (not needed for geo data) - use_arrow=True: Arrow serialization for faster writes - SPATIAL_INDEX=YES: Enable HTTP range request streaming - TEMPORARY_DIR: Use temp dir for sorting large datasets

Variables:: EXTENSIONS (frozenset[str]) – File extensions handled by this writer.

Examples

>>> writer = FlatGeobufCloudWriter()
>>> if writer.supports(cloud_path):
...     writer.write(gdf, cloud_path)

Big-O

O(n) where n is data size, plus network upload time.

EXTENSIONS: Final[frozenset[str]] = frozenset({'.fgb', '.flatgeobuf'})#

supports(cloud_path)[source]#

Check if this writer handles the given path.

Parameters:: cloud_path (CloudPath) – The parsed destination path.
Returns:: True if path is remote and extension is FlatGeobuf.
Return type:: bool

shapelib.core.cloud.writers.generic_cloud_writer module#

Generic cloud writer for any file format.

class shapelib.core.cloud.writers.generic_cloud_writer.GenericCloudWriter[source]#

Bases: BaseCloudWriter

Generic cloud writer for any file format.

This is the fallback writer used when no format-specific writer is registered. It passes arguments directly to gdf.to_file() without format-specific optimizations.

Examples

>>> writer = GenericCloudWriter()
>>> if writer.supports(cloud_path):
...     writer.write(gdf, cloud_path)

Big-O

O(n) where n is data size, plus network upload time.

supports(cloud_path)[source]#

Check if this writer handles the given path.

This is the fallback writer, so it supports any remote path.

Parameters:: cloud_path (CloudPath) – The parsed destination path.
Returns:: True if the path is remote.
Return type:: bool