Reading & saving#

read_file() is the single entry point for loading geospatial data. It detects the format from the file extension, detects whether the path is local or remote, and returns a Lines, Polygons or Points object based on the content.

from shapelib import read_file

shapes = read_file("path/to/file.shp")
type(shapes)  # Lines, Polygons or Points

Supported formats#

Extension

Format

.shp

ESRI Shapefile

.zip

Zipped Shapefile

.geojson / .json

GeoJSON

.gpkg

GeoPackage (pass layer= if needed)

.kml

KML

.fgb

FlatGeobuf

.sqlite

SpatiaLite

Local and remote paths#

The same call works for three kinds of location:

# Local file
lines = read_file("/data/lines.shp")

# Presigned HTTPS URL (e.g. AWS S3) — credentials are in the URL
lines = read_file("https://bucket.s3.amazonaws.com/lines.fgb?X-Amz-Signature=...")

# s3:// protocol — credentials come from the environment
lines = read_file("s3://my-bucket/data/lines.gpkg")

For remote files, cloud-friendly formats (.fgb, .geojson, .gpkg) are streamed with range requests — only the bytes you need are downloaded. The other formats (.shp, .kml, .sqlite) are downloaded to a temporary file first.

Note

For s3:// paths, set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the environment. Presigned HTTPS URLs carry their own credentials and need no setup.

What happens when you read#

read_file does more than open the file — the data comes back already cleaned and validated:

  • null and empty geometries are removed;

  • 3D coordinates are flattened to 2D;

  • encoding problems in column names and values are fixed (shapefiles get multiple-encoding detection and .shx recovery);

  • the CRS is validated, preserved as original_crs, and the best UTM zone for the data is estimated (used later by to_utm()).

Saving#

Every shape object has a save() method that mirrors read_file: the destination can be local or remote and the format follows the extension.

shapes.save("output.shp")                       # local
shapes.save("s3://my-bucket/outputs/output.fgb") # upload to S3
shapes.save()                                    # overwrite the source path

When called without arguments, save() writes back to the path the object was read from.