spatial-polars 0.1.0__py3-none-any.whl

spatial_polars/__init__.py

@@ -0,0 +1,13 @@
+from .io import spatial_series_dtype, scan_spatial, read_spatial
+from .spatialframe import SpatialFrame
+from .spatialseries import SpatialSeries
+from .spatialexpr import SpatialExpr
+
+__all__ = [
+    "spatial_series_dtype",
+    "scan_spatial",
+    "read_spatial",
+    "SpatialFrame",
+    "SpatialSeries",
+    "SpatialExpr",
+]

spatial_polars/_utils.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import polars as pl
+from palettable.palette import Palette
+from polars import selectors as cs
+from matplotlib.colors import Colormap
+
+
+def validate_col_exists_in_df(df: pl.DataFrame, col: Any):
+    if col not in df.columns:
+        # verify column exists in df
+        raise ValueError(
+            f"Input `{col=}` does not exist in frame.  Please provide the name of a column from the dataframe ({df.columns})."
+        )
+
+
+def validate_col_is_numeric(df: pl.DataFrame, col: Any):
+    if df[col].dtype.is_numeric() is False:
+        # verify cmap_col is a numeric dtype.
+        raise ValueError(
+            f"The '{col}' column is not a numeric column.  Please provide a numeric column."
+        )
+
+
+def validate_cmap_input(
+    df: pl.DataFrame,
+    cmap_col: Any,
+    cmap_type: Any,
+    cmap: Any,
+    alpha: Any,
+    normalize_cmap_col: Any,
+):
+    """
+    Validates the input combinations for color mapping options.
+    """
+    if cmap_col is None:
+        # no column provided is always good, use lonboard default color
+        return
+
+    validate_col_exists_in_df(df, cmap_col)
+
+    if cmap_type not in ["categorical", "continuous"]:
+        # verify cmap type is expected
+        raise ValueError(
+            f"`cmap_col` was provided, but {cmap_type=}.  `c_map` must be `categorical` or `continuous` when `cmap_col` is provided."
+        )
+
+    if cmap_type == "continuous":
+        if isinstance(cmap, (Palette, Colormap)) is False:
+            # verify continuous cmaps get a cmap or appropriate type.
+            raise ValueError(
+                f"`{cmap_type=}` is `continuous`, but {cmap=}.  Please provide a palettable.palette.Palette or matplotlib.colors.Colormap when using `cmap_type`=`continuous`."
+            )
+
+        validate_col_is_numeric(df, cmap_col)
+
+    if cmap_type == "categorical":
+        if isinstance(cmap, dict | None) is False:
+            # verify categorical cmaps get a cmap or appropriate type.
+            raise ValueError(
+                "`cmap_type` is `categorical`, but `cmap` is not a dictionary or None.  Please provide a dictionary or None when using `cmap_type`=`categorical`."
+            )
+
+        if isinstance(cmap, dict):
+            # verify values in dataframe column all exist in cmap dictionary keys
+            try:
+                cmap_keys_s = pl.Series("cmap_keys", list(cmap.keys()))
+            except Exception:
+                raise ValueError(
+                    "`cmap_type` is `categorical` and `cmap` is a dictionary, but there was an error converting the dictionary keys to a polars series.  Please provide a dictionary with keys that are all the appropriate datatype for the data in the column."
+                )
+
+            col_vals_and_keys_df = (
+                df[cmap_col]
+                .unique()
+                .to_frame()
+                .join(
+                    cmap_keys_s.to_frame().with_columns(
+                        pl.col("cmap_keys").cast(df[cmap_col].dtype),
+                        pl.lit(True).alias("exists_in_keys"),
+                    ),
+                    how="left",
+                    left_on=cmap_col,
+                    right_on="cmap_keys",
+                )
+            )
+            if col_vals_and_keys_df["exists_in_keys"].is_null().any():
+                missing_values = col_vals_and_keys_df.filter(
+                    pl.col("exists_in_keys").is_null()
+                )[cmap_col].to_list()
+                raise ValueError(
+                    f"`cmap` dictionary keys do not include all values in the data.  Please provide colors for the following values {missing_values}."
+                )
+
+            # verify values have three or four items
+            try:
+                cmap_vals_df = pl.DataFrame(list(cmap.values()), orient="row")
+            except Exception:
+                raise ValueError(
+                    "`cmap` dictionary values could not be converted to a dataframe with three or four integer columns for color codes.  Please provide RGB[A] color codes for all values."
+                )
+
+            col_count = cmap_vals_df.shape[1]
+            if col_count not in [3, 4]:
+                raise ValueError(
+                    "`cmap` dictionary values could not be converted to a dataframe with three or four integer columns for color codes.  Please provide RGB[A] color codes for all values."
+                )
+
+            if col_count == 3:
+                cmap_vals_df.columns = ["R", "G", "B"]
+            elif col_count == 4:
+                cmap_vals_df.columns = ["R", "G", "B", "A"]
+
+            # verify all RGB[A] values are between 0-255
+            oob_rgba_df = cmap_vals_df.select(cmap_keys_s, pl.all()).filter(
+                pl.any_horizontal(
+                    ~cs.by_name("R", "G", "B", "A", require_all=False).is_between(
+                        0, 255, closed="both"
+                    )
+                )
+            )
+
+            if len(oob_rgba_df) > 0:
+                raise ValueError(
+                    f"`cmap` dictionary values for color codes were not all between 0 and 255.  Please provide number between 0-255 for all RGB[A] color codes. Bad values were: {oob_rgba_df}"
+                )
+
+
+def validate_width_and_radius_input(df: pl.DataFrame, width: Any):
+    if width is None:
+        # None is always good
+        return
+
+    elif isinstance(width, float | int):
+        # numbers are always good
+        return
+    elif isinstance(width, np.ndarray):
+        if np.issubdtype(width.dtype, np.number) is False:
+            # validate numpy array dtype is numeric
+            raise ValueError(
+                "Input `width` is a numpy array that is not numeric.  If using a numpy array for the width, the datatype of the array must be numeric."
+            )
+
+        width_len = width.shape[0]
+        df_len = len(df)
+        if width_len != df_len:
+            # validate numpy array has the same number of items as the df
+            raise ValueError(
+                f"Input `width` is a numpy array with a different number of elements than the frame (array: {width_len:,} frame: {df_len:,}).  If using a numpy array for the width, the the array must have the same number of elements as the frame has rows."
+            )
+
+    elif isinstance(width, str):
+        validate_col_exists_in_df(df, width)
+        validate_col_is_numeric(df, width)
+
+    else:
+        raise Exception(
+            f"Input `width` '{width}' is a '{type(width)}', which is not allowed.  Please provide: None, a number, a column name, or a numpy array for the width."
+        )

spatial_polars/io.py

@@ -0,0 +1,459 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Iterator, Optional, TYPE_CHECKING
+
+import polars as pl
+import pyogrio
+import pyproj
+import shapely
+import pyarrow.parquet as _pq
+import json
+
+from polars.io.plugins import register_io_source
+
+if TYPE_CHECKING:
+    from io import BytesIO
+
+__all__ = [
+    "spatial_series_dtype",
+    "scan_spatial",
+    "read_spatial",
+]
+
+spatial_series_dtype = pl.Struct({"wkb_geometry": pl.Binary, "crs": pl.Categorical})
+
+PYOGRIO_POLARS_DTYPES = {
+    "int8": pl.Int8,
+    "int16": pl.Int16,
+    "int32": pl.Int32,
+    "int": pl.Int64,
+    "int64": pl.Int64,
+    "uint8": pl.UInt8,
+    "uint16": pl.UInt16,
+    "uint32": pl.UInt32,
+    "uint": pl.UInt64,
+    "uint64": pl.UInt64,
+    "bool": pl.Boolean,
+    "float32": pl.Float32,
+    "float": pl.Float64,
+    "float64": pl.Float64,
+    "datetime64[D]": pl.Date,
+    "datetime64[us]": pl.Datetime("us"),
+    "datetime64[ns]": pl.Datetime("ns"),
+    "datetime64[ms]": pl.Datetime("ms"),
+    "datetime64": pl.Datetime("ms"),  # ms??
+    "object": pl.String,
+}
+
+
+def scan_spatial(
+    path_or_buffer: str | Path | BytesIO,
+    layer: Optional[str | int] = None,
+    encoding: Optional[str] = None,
+    bbox: Optional[tuple[float, float, float, float]] = None,
+    mask: Optional[shapely.Polygon] = None,
+) -> pl.LazyFrame:
+    r"""
+    Scans a data source [supported by pyogrio](https://pyogrio.readthedocs.io/en/stable/supported_formats.html) or a geoparquet file to produce a polars LazyFrame.
+
+    Note
+    ----
+    Although geoparquet is supported, this implementation, in its current state, leaves a lot to be desired.
+
+    Parameters
+    ----------
+
+    path_or_buffer
+        A dataset path or URI, raw buffer, or file-like object with a read method.
+
+    layer
+        If an integer is provided, it corresponds to the index of the layer with the
+        data source. If a string is provided, it must match the name of the layer in
+        the data source. Defaults to first layer in data source.
+
+    encoding
+        If present, will be used as the encoding for reading string values from the
+        data source. By default will automatically try to detect the native encoding
+        and decode to UTF-8.
+
+    bbox
+        If present, will be used to filter records whose geometry intersects this
+        box. This must be in the same CRS as the dataset. If GEOS is present and
+        used by GDAL, only geometries that intersect this bbox will be returned;
+        if GEOS is not available or not used by GDAL, all geometries with bounding
+        boxes that intersect this bbox will be returned. Cannot be combined with mask
+        keyword.  Tuple should be in the format of (xmin, ymin, xmax, ymax).
+
+    mask
+        If present, will be used to filter records whose geometry intersects this
+        geometry. This must be in the same CRS as the dataset. If GEOS is present
+        and used by GDAL, only geometries that intersect this geometry will be
+        returned; if GEOS is not available or not used by GDAL, all geometries with
+        bounding boxes that intersect the bounding box of this geometry will be
+        returned. Requires Shapely >= 2.0. Cannot be combined with bbox keyword.
+
+    Examples
+    --------
+    **Scanning a layer from a geopackage:**
+
+    >>> my_geopackage = r"c:\data\hiking_club.gpkg"
+    >>> lf = scan_spatial(my_geopackage, layer="hike")
+    >>> lf
+    naive plan: (run LazyFrame.explain(optimized=True) to see the optimized plan)
+    PYTHON SCAN []
+    PROJECT */4 COLUMNS
+
+    **Scanning a shapefile:**
+
+    >>> from spatial_polars import scan_spatial
+    >>> my_shapefile = r"c:\data\roads.shp"
+    >>> lf = scan_spatial(my_shapefile)
+    >>> lf
+    naive plan: (run LazyFrame.explain(optimized=True) to see the optimized plan)
+    PYTHON SCAN []
+    PROJECT */11 COLUMNS
+
+    **Scanning a shapefile from within a zipped directory:**
+
+    >>> zipped_shapefiles = r"C:\data\illinois-latest-free.shp.zip"
+    >>> lf = scan_spatial(zipped_shapefiles, layer="gis_osm_roads_free_1")
+    >>> lf
+    naive plan: (run LazyFrame.explain(optimized=True) to see the optimized plan)
+    PYTHON SCAN []
+    PROJECT */11 COLUMNS
+    """
+    if isinstance(path_or_buffer, (str, Path)) and str(path_or_buffer).endswith(
+        ".parquet"
+    ):
+        # TODO look into libgdal-arrow-parquet from conda forge
+        # https://pyogrio.readthedocs.io/en/latest/install.html#conda-forge
+        schema = pl.scan_parquet(path_or_buffer).collect_schema()
+        if schema.get("geometry") is not None:
+            schema["geometry"] = spatial_series_dtype
+        if bbox is not None:
+            mask = shapely.Polygon(shapely.box(*bbox))
+
+        def source_generator(
+            with_columns: list[str] | None,
+            predicate: pl.Expr | None,
+            n_rows: int | None,
+            batch_size: int | None,
+        ) -> Iterator[pl.DataFrame]:
+            """
+            Generator function that creates the source.
+            This function will be registered as IO source.
+            """
+            if mask is not None:
+                if "geometry" not in with_columns:
+                    with_columns.append("geometry")
+
+            tab = _pq.read_table(path_or_buffer)
+            tab_metadata = tab.schema.metadata if tab.schema.metadata else {}
+            if b"geo" in tab_metadata:
+                geo_meta = json.loads(tab_metadata[b"geo"])
+            else:
+                geo_meta = {}
+            geom_col = geo_meta["primary_column"]
+            crs_wkt = pyproj.CRS(geo_meta["columns"][geom_col]["crs"]).to_wkt()
+
+            if batch_size is None:
+                batch_size = 10000
+
+            if with_columns is None:
+                read_geometry = True
+            elif "geometry" in with_columns:
+                read_geometry = True
+            else:
+                read_geometry = False
+
+            lf = pl.scan_parquet(path_or_buffer)
+
+            if with_columns is not None:
+                lf = lf.select(with_columns)
+
+            if predicate is not None:
+                lf = lf.filter(predicate)
+
+            previous_max = 0
+            while n_rows is None or n_rows > 0:
+                batch = lf.slice(previous_max, previous_max + batch_size).collect()
+                if batch.height is None or batch.height == 0:
+                    break
+                if n_rows is not None and n_rows <= 0:
+                    break
+
+                if read_geometry:
+                    # get the geometries from the batch
+                    geometries = batch[0:n_rows][geom_col]
+                    shapely_goms = shapely.from_wkb(geometries)
+                    geometries = shapely.to_wkb(shapely_goms)
+
+                    # create the dataframe with the non geometry columns
+                    # then add struct column with the WKB geometries/CRS
+                    df = pl.DataFrame(batch[0:n_rows].drop(geom_col)).with_columns(
+                        pl.struct(
+                            pl.Series("wkb_geometry", geometries, dtype=pl.Binary),
+                            pl.lit(crs_wkt, dtype=pl.Categorical).alias("crs"),
+                        ).alias("geometry")
+                    )
+                else:
+                    df = pl.DataFrame(batch[0:n_rows])
+                previous_max += df.height
+
+                if n_rows is not None:
+                    n_rows -= df.height
+
+                if predicate is not None:
+                    df = df.filter(predicate)
+
+                if mask is not None:
+                    df = df.filter(pl.col("geometry").spatial.intersects(mask))
+                if mask is not None:
+                    if "geometry" not in with_columns:
+                        df = df.drop("geometry")
+
+                yield df
+
+    else:
+        # not geoparquet
+        layer_info = pyogrio.read_info(path_or_buffer, layer=layer, encoding=encoding)
+        schema = dict(
+            zip(
+                layer_info["fields"],
+                [PYOGRIO_POLARS_DTYPES[dt] for dt in layer_info["dtypes"]],
+            )
+        )
+        if layer_info.get("geometry_type"):
+            schema["geometry"] = spatial_series_dtype
+
+        def source_generator(
+            with_columns: list[str] | None,
+            predicate: pl.Expr | None,
+            n_rows: int | None,
+            batch_size: int | None,
+        ) -> Iterator[pl.DataFrame]:
+            """
+            Generator function that creates the source.
+            This function will be registered as IO source.
+            """
+
+            if batch_size is None:
+                batch_size = 100
+
+            if with_columns is None:
+                read_geometry = True
+            elif "geometry" in with_columns:
+                read_geometry = True
+                with_columns.remove("geometry")
+            else:
+                read_geometry = False
+
+            with pyogrio.open_arrow(
+                path_or_buffer,
+                layer=layer,
+                encoding=encoding,
+                columns=with_columns,
+                read_geometry=read_geometry,
+                force_2d=False,
+                bbox=bbox,
+                mask=mask,
+                batch_size=batch_size,
+                use_pyarrow=True,
+            ) as source:
+                meta, reader = source
+
+                # extract the crs from the metadata
+                crs_wkt = pyproj.CRS(meta["crs"]).to_wkt()
+
+                geom_col = meta["geometry_name"] or "wkb_geometry"
+
+                while n_rows is None or n_rows > 0:
+                    for batch in reader:
+                        if n_rows is not None and n_rows <= 0:
+                            break
+
+                        if read_geometry:
+                            # get the geometries from the batch
+                            geometries = batch[geom_col][0:n_rows]
+                            shapely_goms = shapely.from_wkb(geometries)
+                            geometries = shapely.to_wkb(shapely_goms)
+
+                            print(batch)
+
+                            # create the dataframe with the non geometry columns
+                            # then add struct column with the WKB geometries/CRS
+                            df = pl.DataFrame(
+                                batch[0:n_rows].drop_columns(geom_col)
+                            ).with_columns(
+                                pl.struct(
+                                    pl.Series(
+                                        "wkb_geometry", geometries, dtype=pl.Binary
+                                    ),
+                                    pl.lit(crs_wkt, dtype=pl.Categorical).alias("crs"),
+                                ).alias("geometry")
+                            )
+                        else:
+                            df = pl.DataFrame(batch[0:n_rows])
+
+                        if n_rows is not None:
+                            n_rows -= df.height
+
+                        if predicate is not None:
+                            df = df.filter(predicate)
+
+                        yield df
+                    if n_rows is None or n_rows <= 0:
+                        break
+
+    return register_io_source(io_source=source_generator, schema=schema)
+
+
+def read_spatial(
+    path_or_buffer: str | Path | BytesIO,
+    layer: Optional[str | int] = None,
+    encoding: Optional[str] = None,
+    bbox: Optional[tuple[float, float, float, float]] = None,
+    mask: Optional[shapely.Polygon] = None,
+) -> pl.DataFrame:
+    r"""
+    Reads a spatial data source [supported by pyogrio](https://pyogrio.readthedocs.io/en/stable/supported_formats.html) to produce a polars DataFrame.
+
+    Note
+    ----
+    Although geoparquet is supported, this implementation, in its current state, leaves a lot to be desired.
+
+    Parameters
+    ----------
+
+    path_or_buffer
+        A dataset path or URI, raw buffer, or file-like object with a read method.
+
+    layer
+        If an integer is provided, it corresponds to the index of the layer with the
+        data source. If a string is provided, it must match the name of the layer in
+        the data source. Defaults to first layer in data source.
+
+    encoding
+        If present, will be used as the encoding for reading string values from the
+        data source. By default will automatically try to detect the native encoding
+        and decode to UTF-8.
+
+    bbox
+        If present, will be used to filter records whose geometry intersects this
+        box. This must be in the same CRS as the dataset. If GEOS is present and
+        used by GDAL, only geometries that intersect this bbox will be returned;
+        if GEOS is not available or not used by GDAL, all geometries with bounding
+        boxes that intersect this bbox will be returned. Cannot be combined with mask
+        keyword.  Tuple should be in the format of (xmin, ymin, xmax, ymax).
+
+    mask
+        If present, will be used to filter records whose geometry intersects this
+        geometry. This must be in the same CRS as the dataset. If GEOS is present
+        and used by GDAL, only geometries that intersect this geometry will be
+        returned; if GEOS is not available or not used by GDAL, all geometries with
+        bounding boxes that intersect the bounding box of this geometry will be
+        returned. Requires Shapely >= 2.0. Cannot be combined with bbox keyword.
+
+    Examples
+    --------
+    **Scanning a layer from a geopackage:**
+
+    >>> from spatial_polars import read_spatial
+    >>> my_geopackage = r"c:\data\hiking_club.gpkg"
+    >>> df = read_spatial(my_geopackage, layer="hike")
+    >>> df
+    shape: (31, 4)
+    ┌─────────────────────────────────┬────────────┬──────────┬─────────────────────────────────┐
+    │ LOCATION                        ┆ DATE       ┆ DISTANCE ┆ geometry                        │
+    │ ---                             ┆ ---        ┆ ---      ┆ ---                             │
+    │ str                             ┆ date       ┆ f64      ┆ struct[2]                       │
+    ╞═════════════════════════════════╪════════════╪══════════╪═════════════════════════════════╡
+    │ Watershed Nature Center         ┆ 2023-01-14 ┆ 1.25     ┆ {b"\x01\x02\x00\x00\x00\xd8\x0… │
+    │ Ellis Island                    ┆ 2023-03-11 ┆ 2.25     ┆ {b"\x01\x02\x00\x00\x00\x82\x0… │
+    │ Cahokia Mounds State Historic … ┆ 2023-02-04 ┆ 1.75     ┆ {b"\x01\x02\x00\x00\x00\xb1\x0… │
+    │ Willoughby Heritage Farm        ┆ 2022-12-03 ┆ 0.75     ┆ {b"\x01\x02\x00\x00\x00\xef\x0… │
+    │ Pere Marquette State Park       ┆ 2022-10-15 ┆ 1.0      ┆ {b"\x01\x02\x00\x00\x002\x02\x… │
+    │ …                               ┆ …          ┆ …        ┆ …                               │
+    │ Haunted Glen Carbon             ┆ 2024-10-19 ┆ 1.75     ┆ {b"\x01\x02\x00\x00\x00\x82\x0… │
+    │ Watershed Nature Center         ┆ 2024-10-08 ┆ 1.0      ┆ {b"\x01\x02\x00\x00\x000\x00\x… │
+    │ Beaver Dam State Park           ┆ 2024-10-26 ┆ 2.0      ┆ {b"\x01\x02\x00\x00\x00\xc4\x0… │
+    │ Willoughby Heritage Farm        ┆ 2024-12-07 ┆ 1.5      ┆ {b"\x01\x02\x00\x00\x00>\x02\x… │
+    │ Cahokia Mounds State Historic … ┆ 2025-03-08 ┆ 1.75     ┆ {b"\x01\x02\x00\x00\x00\xeb\x0… │
+    └─────────────────────────────────┴────────────┴──────────┴─────────────────────────────────┘
+
+    **Scanning a shapefile:**
+
+    >>> my_shapefile = r"c:\data\roads.shp"
+    >>> df = read_spatial(my_shapefile)
+    >>> df
+    shape: (1_662_837, 11)
+    ┌────────────┬──────┬─────────────┬─────────────┬───┬───────┬────────┬────────┬────────────────────┐
+    │ osm_id     ┆ code ┆ fclass      ┆ name        ┆ … ┆ layer ┆ bridge ┆ tunnel ┆ geometry           │
+    │ ---        ┆ ---  ┆ ---         ┆ ---         ┆   ┆ ---   ┆ ---    ┆ ---    ┆ ---                │
+    │ str        ┆ i32  ┆ str         ┆ str         ┆   ┆ i64   ┆ str    ┆ str    ┆ struct[2]          │
+    ╞════════════╪══════╪═════════════╪═════════════╪═══╪═══════╪════════╪════════╪════════════════════╡
+    │ 4265057    ┆ 5114 ┆ secondary   ┆ 55th Street ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x03\x0…      │
+    │ 4265058    ┆ 5114 ┆ secondary   ┆ Fairview    ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆ Avenue      ┆   ┆       ┆        ┆        ┆ 0\x00\x0e\x0…      │
+    │ 4267607    ┆ 5114 ┆ secondary   ┆ 31st Street ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x02\x0…      │
+    │ 4271616    ┆ 5115 ┆ tertiary    ┆ 59th Street ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x15\x0…      │
+    │ 4275365    ┆ 5122 ┆ residential ┆ 61st Street ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00"\x00\x…      │
+    │ …          ┆ …    ┆ …           ┆ …           ┆ … ┆ …     ┆ …      ┆ …      ┆ …                  │
+    │ 1370383592 ┆ 5153 ┆ footway     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x02\x0…      │
+    │ 1370383593 ┆ 5153 ┆ footway     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x07\x0…      │
+    │ 1370383594 ┆ 5153 ┆ footway     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x1c\x0…      │
+    │ 1370383595 ┆ 5153 ┆ footway     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x0b\x0…      │
+    │ 1370398885 ┆ 5141 ┆ service     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x02\x0…      │
+    └────────────┴──────┴─────────────┴─────────────┴───┴───────┴────────┴────────┴────────────────────┘
+
+    **Scanning a shapefile from within a zipped directory:**
+
+    >>> zipped_shapefiles = r"C:\data\illinois-latest-free.shp.zip"
+    >>> df = read_spatial(zipped_shapefiles, layer="gis_osm_roads_free_1")
+    >>> df
+    shape: (1_662_837, 11)
+    ┌────────────┬──────┬─────────────┬─────────────┬───┬───────┬────────┬────────┬────────────────────┐
+    │ osm_id     ┆ code ┆ fclass      ┆ name        ┆ … ┆ layer ┆ bridge ┆ tunnel ┆ geometry           │
+    │ ---        ┆ ---  ┆ ---         ┆ ---         ┆   ┆ ---   ┆ ---    ┆ ---    ┆ ---                │
+    │ str        ┆ i32  ┆ str         ┆ str         ┆   ┆ i64   ┆ str    ┆ str    ┆ struct[2]          │
+    ╞════════════╪══════╪═════════════╪═════════════╪═══╪═══════╪════════╪════════╪════════════════════╡
+    │ 4265057    ┆ 5114 ┆ secondary   ┆ 55th Street ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x03\x0…      │
+    │ 4265058    ┆ 5114 ┆ secondary   ┆ Fairview    ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆ Avenue      ┆   ┆       ┆        ┆        ┆ 0\x00\x0e\x0…      │
+    │ 4267607    ┆ 5114 ┆ secondary   ┆ 31st Street ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x02\x0…      │
+    │ 4271616    ┆ 5115 ┆ tertiary    ┆ 59th Street ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x15\x0…      │
+    │ 4275365    ┆ 5122 ┆ residential ┆ 61st Street ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00"\x00\x…      │
+    │ …          ┆ …    ┆ …           ┆ …           ┆ … ┆ …     ┆ …      ┆ …      ┆ …                  │
+    │ 1370383592 ┆ 5153 ┆ footway     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x02\x0…      │
+    │ 1370383593 ┆ 5153 ┆ footway     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x07\x0…      │
+    │ 1370383594 ┆ 5153 ┆ footway     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x1c\x0…      │
+    │ 1370383595 ┆ 5153 ┆ footway     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x0b\x0…      │
+    │ 1370398885 ┆ 5141 ┆ service     ┆ null        ┆ … ┆ 0     ┆ F      ┆ F      ┆ {b"\x01\x02\x00\x0 │
+    │            ┆      ┆             ┆             ┆   ┆       ┆        ┆        ┆ 0\x00\x02\x0…      │
+    └────────────┴──────┴─────────────┴─────────────┴───┴───────┴────────┴────────┴────────────────────┘
+
+    """
+    return scan_spatial(
+        path_or_buffer=path_or_buffer,
+        layer=layer,
+        encoding=encoding,
+        bbox=bbox,
+        mask=mask,
+    ).collect(engine="streaming")