shapelib.adapters package#

Submodules#

shapelib.adapters.read_file module#

Adapter for reading geospatial files from local or remote storage.

shapelib.adapters.read_file.read_file(path, *, keep_z=False, **kwargs)[source]#

Read a geospatial file from local or remote storage.

This function automatically detects whether the path is a local file or a remote URL and routes to the appropriate handler. Supports local files, HTTPS URLs (including presigned S3 URLs), and s3:// protocol.

Parameters:

path (str | Path) – The path to the geospatial file. Can be: - A local file path (string or Path object) - An HTTPS URL (including presigned AWS S3 URLs) - An S3 URL (s3://bucket/key)
keep_z (bool) – Keep the Z coordinate of 3-D geometries. Defaults to False, which flattens every geometry to 2-D. Turn it on when Z is data, such as the elevation of each vertex of a contour line; it is kept by the copies, filters and reprojections of the returned object too.
**kwargs (Any) – Additional arguments passed to the file handler (e.g., layer name for GeoPackage files).

Returns:

A geometry object (Polygons, Lines, Points, or Empty) containing the file’s data with full spatial functionality.

Return type:

BaseShapes

Raises:

FileNotFoundError – If the file (local or remote) does not exist.
ValueError – If the file format is not supported.
ConnectionError – If a remote file cannot be accessed.
PermissionError – If access to the file is denied.

Examples

Read a local shapefile:

>>> polygons = read_file("/path/to/shapefile.shp")
>>> print(polygons.get_total_area())

Read from a presigned S3 URL (streaming for FlatGeobuf):

>>> lines = read_file(
...     "https://bucket.s3.amazonaws.com/file.fgb?X-Amz-Signature=..."
... )

Read using S3 protocol (requires AWS credentials in environment):

>>> points = read_file("s3://my-bucket/data/points.gpkg")

Keep the elevation of 3-D contour lines:

>>> contours = read_file("/path/to/contours.fgb", keep_z=True)
>>> bool(contours.has_z.all())
True

Big-O

Local: O(n) where n is file size. Remote streaming (.fgb, .gpkg, .geojson): O(n) with range requests. Remote download (.shp, .kml, .sqlite): O(n) + network latency.

Notes

For remote files, the handler selection is based on file extension: - Streaming (vsicurl): .fgb, .geojson, .json, .gpkg - Download to temp: .shp, .kml, .sqlite

AWS credentials for s3:// protocol should be set via environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY. Presigned HTTPS URLs include credentials and don’t require env vars.