read_gdf

read_gdf(
    source,
    *,
    entity=None,
    entity_name=None,
    layer=None,
    crs=None,
    make_valid=True,
)

Read user geometry into a validated GeoDataFrame (the geometry entry point).

Accepts a GeoDataFrame or a path to a shapefile (plain or zipped), GeoJSON, or GeoPackage, and enforces the geometry contract every spatial function relies on: a declared CRS, no empty/missing geometries (invalid ones repaired), and a unique entity id. The resolved ids are stored on gdf.attrs["geometrics_geo"] so later calls can omit entity=.

Parameters

Name	Type	Description	Default
source	gpd.GeoDataFrame | str | Path	A :class:geopandas.GeoDataFrame (copied, never mutated) or a path to a .shp / .zip / .geojson / .json / .gpkg file.	required
entity	str | None	Name of the entity (unit) id column. When None it is resolved automatically: the sole non-geometry column if there is exactly one, else a column whose name matches the entity-id hints (id / code / region / …).	None
entity_name	str | None	Optional column holding a human-readable label for each unit (e.g. a district name next to a census code).	None
layer	str | None	Layer name for multi-layer sources (GeoPackage), forwarded to :func:geopandas.read_file.	None
crs	Any | None	Coordinate reference system to declare (set_crs) when the source carries none. read_gdf never reprojects — use :func:ensure_metric_crs for that.	None
make_valid	bool	Repair invalid geometries with :func:shapely.make_valid (a :class:~geometrics.GeometricsWarning reports how many were repaired).	True

Returns

Name	Type	Description
	geopandas.GeoDataFrame	The validated geometry, with attrs["geometrics_geo"] recording the resolved entity (and entity_name).

Raises

Name	Type	Description
	TypeError	If source is neither a GeoDataFrame nor a path.
	KeyError	If an explicit entity / entity_name column is absent.
	ValueError	If the format is unsupported, no CRS is declared and crs is None, the entity cannot be resolved, ids are duplicated, or geometries are empty/missing.

Examples

Validate an in-memory GeoDataFrame (the entity id is auto-resolved):

import geopandas as gpd
from shapely.geometry import box

from geometrics._geo import read_gdf

gdf = gpd.GeoDataFrame(
    {"region": ["A", "B"]},
    geometry=[box(0, 0, 1, 1), box(1, 0, 2, 1)],
    crs="EPSG:4326",
)
validated = read_gdf(gdf)
validated.attrs["geometrics_geo"]["entity"]