shapelib.core.cloud.providers package#

Cloud storage providers for different protocols.

Submodules#

shapelib.core.cloud.providers.cloud_provider module#

Protocol defining the interface for cloud storage providers.

class shapelib.core.cloud.providers.cloud_provider.CloudProvider(*args, **kwargs)[source]#

Bases: Protocol

Protocol defining the interface for cloud storage providers.

Each cloud provider (S3, HTTPS, GCS, Azure) implements this interface to handle file operations for their specific storage system.

This follows the Strategy pattern, allowing GeoCloudFactory to delegate operations to the appropriate provider without conditional logic.

Examples

>>> class MyCloudProvider:
...     def supports(self, cloud_path: CloudPath) -> bool:
...         return cloud_path.scheme == "mycloud"
...
...     def upload(self, source: Path, cloud_path: CloudPath) -> None:
...         # Upload implementation
...         ...

Big-O

All operations are O(n) where n is the file size.

supports(cloud_path)[source]#

Check if this provider handles the given cloud path.

Parameters:: cloud_path (CloudPath) – The parsed cloud path to check.
Returns:: True if this provider can handle the path.
Return type:: bool

upload(source, cloud_path)[source]#

Upload a local file to cloud storage.

Parameters:

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

Raises:

FileNotFoundError – If the source file does not exist.
ConnectionError – If the upload fails.
PermissionError – If access is denied.

Return type:

None

download(cloud_path, destination)[source]#

Download a remote file to local storage.

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.

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.core.cloud.providers.https_provider module#

HTTPS cloud storage provider for presigned URLs.

class shapelib.core.cloud.providers.https_provider.HttpsProvider[source]#

Bases: object

Cloud provider for HTTPS URLs (including presigned URLs).

Handles file operations using the requests library for HTTP/HTTPS URLs. Works with presigned URLs from any cloud provider (AWS, GCS, Azure).

Examples

>>> provider = HttpsProvider()
>>> provider.supports(CloudPath.from_string("https://example.com/file.fgb"))
True

Big-O

All operations are O(n) where n is the file size.

supports(cloud_path)[source]#

Check if this provider handles HTTPS URLs.

Parameters:: cloud_path (CloudPath) – The parsed cloud path to check.
Returns:: True if the path uses http:// or https:// protocol.
Return type:: bool

upload(source, cloud_path)[source]#

Upload a local file via HTTPS PUT (presigned URL).

Parameters:

source (Path) – The local file to upload.
cloud_path (CloudPath) – The HTTPS destination URL (presigned PUT URL).

Raises:

FileNotFoundError – If the source file does not exist.
ConnectionError – If the upload fails.
PermissionError – If access is denied (403).

Return type:

None

download(cloud_path, destination)[source]#

Download a file via HTTPS GET.

Parameters:

cloud_path (CloudPath) – The HTTPS source URL.
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 (404).
ConnectionError – If the download fails.
PermissionError – If access is denied (403).

file_exists(cloud_path)[source]#

Check if an HTTPS resource exists using HEAD request.

Parameters:: cloud_path (CloudPath) – The HTTPS URL to check.
Returns:: True if the resource exists (HTTP 200), False otherwise.
Return type:: bool

shapelib.core.cloud.providers.s3_provider module#

AWS S3 cloud storage provider.

class shapelib.core.cloud.providers.s3_provider.S3Provider[source]#

Bases: object

Cloud provider for AWS S3 storage.

Handles file operations using the boto3 library for s3:// protocol URLs.

Examples

>>> provider = S3Provider()
>>> provider.supports(CloudPath.from_string("s3://bucket/file.fgb"))
True

Big-O

All operations are O(n) where n is the file size.

supports(cloud_path)[source]#

Check if this provider handles S3 protocol paths.

Parameters:: cloud_path (CloudPath) – The parsed cloud path to check.
Returns:: True if the path uses s3:// protocol.
Return type:: bool

upload(source, cloud_path)[source]#

Upload a local file to S3.

Parameters:

source (Path) – The local file to upload.
cloud_path (CloudPath) – The S3 destination path (s3://bucket/key).

Raises:

ImportError – If boto3 is not installed.
FileNotFoundError – If the source file does not exist.
ConnectionError – If the upload fails.
PermissionError – If access is denied.

Return type:

None

download(cloud_path, destination)[source]#

Download a file from S3.

Parameters:

cloud_path (CloudPath) – The S3 source path (s3://bucket/key).
destination (Path) – The local destination path.

Returns:

The path to the downloaded file.

Return type:

Path

Raises:

ImportError – If boto3 is not installed.
FileNotFoundError – If the S3 object does not exist.
ConnectionError – If the download fails.
PermissionError – If access is denied.

file_exists(cloud_path)[source]#

Check if an S3 object exists using head_object.

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