Skip to content

Lazy feature collection#

The lazy vector type returned by the lazy vector reads.

Module pyramids_lazy._lazy_collection
Public as pyramids.feature.LazyFeatureCollection
Extra required parquet (pyarrow, dask-geopandas)

What it is — and is not#

A LazyFeatureCollection is a dask_geopandas.GeoDataFrame. It is not a FeatureCollection and not a geopandas.GeoDataFrame. Both it and the eager FeatureCollection satisfy core's SpatialObject protocol, so a consumer accepts either through isinstance(x, SpatialObject) rather than by checking for a concrete class.

That subclass relationship is why the whole dask-geopandas API is available directly on the object — npartitions, spatial_shuffle(), compute(), the geometry accessors — rather than being re-exposed method by method.

Why the import is deferred#

This module hard-imports dask_geopandas, which only the parquet extra installs. The class is therefore resolved through a module-level __getattr__ on the package root, so importing pyramids_lazy on a minimal install never evaluates this file. LazyNetCDF, which needs only dask, is imported eagerly instead.

Pickling is handled explicitly: a reconstruction hook rebuilds the subclass rather than letting dask's default reduce return a plain dask_geopandas.GeoDataFrame, so a round trip through a distributed worker preserves the type.

API#

pyramids_lazy._lazy_collection.LazyFeatureCollection #

Bases: GeoDataFrame

Lazy vector collection backed by a dask_geopandas graph.

Subclasses :class:dask_geopandas.GeoDataFrame — every method of that parent is available unchanged (to_crs, clip, sjoin, .npartitions, .spatial_partitions). Overrides: compute / persist return pyramids-native wrappers, spatial_shuffle re-wraps the shuffled result, to_file / plot raise with actionable messages, and read_file is a classmethod delegating back to the eager reader so the :class:~pyramids.base.protocols.SpatialObject protocol is satisfied.

Construct via FeatureCollection.read_file(..., backend='dask') or FeatureCollection.read_parquet(..., backend='dask'). Direct construction is discouraged; use :meth:LazyFeatureCollection.from_dask_gdf if you must wrap a pre-built dask-geopandas frame.

Note

On installs without the [parquet] extra, importing this class from :mod:pyramids.feature returns None (sentinel). Consumer code using isinstance must guard explicitly: if LazyFeatureCollection is not None and isinstance(x, LazyFeatureCollection):....

Source code in src/pyramids_lazy/_lazy_collection.py
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
class LazyFeatureCollection(dask_geopandas.GeoDataFrame):
    """Lazy vector collection backed by a dask_geopandas graph.

    Subclasses :class:`dask_geopandas.GeoDataFrame` — every method of that
    parent is available unchanged (`to_crs`, `clip`, `sjoin`,
    `.npartitions`, `.spatial_partitions`). Overrides: `compute` /
    `persist` return pyramids-native wrappers, `spatial_shuffle`
    re-wraps the shuffled result, `to_file` / `plot` raise with
    actionable messages, and `read_file` is a classmethod delegating
    back to the eager reader so the
    :class:`~pyramids.base.protocols.SpatialObject` protocol is satisfied.

    Construct via `FeatureCollection.read_file(..., backend='dask')` or
    `FeatureCollection.read_parquet(..., backend='dask')`. Direct
    construction is discouraged; use
    :meth:`LazyFeatureCollection.from_dask_gdf` if you must wrap a
    pre-built dask-geopandas frame.

    Note:
        On installs without the `[parquet]` extra, importing this
        class from :mod:`pyramids.feature` returns `None` (sentinel).
        Consumer code using `isinstance` must guard explicitly:
        `if LazyFeatureCollection is not None and isinstance(x, LazyFeatureCollection):...`.
    """

    def __getattribute__(self, name: str) -> Any:
        """Return a class-swapped view of every inherited method's result.

        dask-geopandas inherits from dask-expr and does not honour pandas'
        classic `_constructor` hook. Methods like `to_crs`, `clip`,
        `sjoin`, `copy`, `drop_duplicates` go through
        `map_partitions` with meta inference and produce a plain
        :class:`dask_geopandas.GeoDataFrame`, silently dropping the
        :class:`LazyFeatureCollection` subclass. This hook wraps every
        public callable so that a :class:`dask_geopandas.GeoDataFrame`
        result is rebranded back to the subclass before it reaches the
        caller. Private names (`_`-prefixed) are passed through
        unchanged to keep dask-expr internals — meta inference, name
        caches, partition probing — on the hot path they expect.
        """
        attr = object.__getattribute__(self, name)
        if name.startswith("_") or not callable(attr):
            return attr
        cls = type(self)

        @functools.wraps(attr)
        def wrapper(*args: Any, **kwargs: Any) -> Any:
            result = attr(*args, **kwargs)
            if isinstance(result, dask_geopandas.GeoDataFrame) and not isinstance(
                result,
                cls,
            ):
                result = cls.from_dask_gdf(result)
            elif isinstance(result, geopandas.GeoDataFrame) and not isinstance(
                result,
                geopandas.GeoSeries,
            ):
                from pyramids.feature import FeatureCollection

                # Skip the wrap when the method (e.g. an overridden `compute`) already
                # returned a FeatureCollection, avoiding a redundant double-wrap (ARC-63).
                if not isinstance(result, FeatureCollection):
                    result = FeatureCollection(result)
            return result

        return wrapper

    @classmethod
    def from_dask_gdf(cls, dask_gdf: Any) -> LazyFeatureCollection:
        """Wrap an existing :class:`dask_geopandas.GeoDataFrame` as a LazyFC.

        This is the canonical construction path for code that already holds
        a pre-built :class:`dask_geopandas.GeoDataFrame` (for example,
        from :func:`dask_geopandas.from_geopandas` or a third-party reader)
        and wants to use it through the pyramids type system.

        Implementation uses class-swap (`copy()` + `__class__`
        assignment) rather than a four-arg reconstruction, because
        `(dask, _name, _meta, divisions)` is private dask.dataframe API
        that shifted between dask-expr and legacy. Class-swap relies only
        on Python's object model and survives upstream churn. The
        invariant "`LazyFeatureCollection` adds no extra instance state
        beyond :class:`dask_geopandas.GeoDataFrame`" is pinned by
        :func:`tests.feature.test_lazy_feature_collection.test_from_dask_gdf_preserves_state`.

        Args:
            dask_gdf: Pre-built `dask_geopandas.GeoDataFrame` to wrap.

        Returns:
            LazyFeatureCollection: A view over `dask_gdf` whose
            `__class__` has been rebound to LazyFeatureCollection.
            The task graph, partition names, metadata, and divisions
            are unchanged — only the concrete class is swapped.

        Examples:
            - Wrap a fresh dask_geopandas frame:
                ```python
                >>> import geopandas as gpd
                >>> import dask_geopandas as dg
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import LazyFeatureCollection
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": [1, 2]},
                ...     geometry=[Point(0, 0), Point(1, 1)],
                ...     crs="EPSG:4326",
                ... )
                >>> ddf = dg.from_geopandas(gdf, npartitions=1)
                >>> lfc = LazyFeatureCollection.from_dask_gdf(ddf)
                >>> lfc.npartitions
                1
                >>> lfc.epsg
                4326

                ```
        """
        result = dask_gdf.copy()
        result.__class__ = cls
        return cast("LazyFeatureCollection", result)

    # Deprecated alias kept for one release cycle. Old callsites
    # (readers inside collection.py, tests) can transition at their own
    # pace; remove the alias in a follow-up commit.
    _from_dask_gdf = from_dask_gdf

    def __reduce__(self):
        """Preserve the LazyFeatureCollection class across pickle round-trips.

        `from_dask_gdf` uses `result.__class__ = cls` to rebind the
        concrete class. The parent's default `__reduce__` reconstructs
        with the base :class:`dask_geopandas.GeoDataFrame`, silently
        dropping the subclass on unpickle. Wrapping super's reduce tuple
        in a module-level trampoline re-applies the class swap.
        """
        return (_rebuild_lazy_fc, (super().__reduce__(),))

    @classmethod
    def read_file(
        cls,
        path: str | Path,
        *,
        npartitions: int | None = None,
        chunksize: int | None = None,
        **kwargs: Any,
    ) -> LazyFeatureCollection:
        """Construct a LazyFC from a vector file.

        Satisfies the :class:`~pyramids.base.protocols.SpatialObject`
        protocol's `read_file` classmethod requirement. Delegates to
        :meth:`FeatureCollection.read_file` with `backend='dask'`.

        The import of :class:`FeatureCollection` is inline by
        necessity — :mod:`pyramids.feature.collection` imports this module
        from inside its dask branch, so a top-of-file import here would
        form a cycle. Per `CLAUDE.md`, circular-import breaks are an
        accepted exception to the no-inline-imports rule.

        Args:
            path: Path to a vector file GDAL/OGR can open (GeoJSON,
                Shapefile, GeoPackage, FlatGeobuf, …).
            npartitions: Target number of dask partitions. Mutually
                exclusive with `chunksize`.
            chunksize: Target rows per partition. Mutually exclusive
                with `npartitions`.
            **kwargs: Forwarded to :meth:`FeatureCollection.read_file`.
                Filter kwargs (`bbox` / `mask` / `rows` /
                `columns` / `where` / `layer`) are rejected
                because dask-geopandas has no pushdown for them.

        Returns:
            LazyFeatureCollection: A new lazy FC.

        Examples:
            - Read a small GeoJSON as a lazy FC via the classmethod:
                ```python
                >>> import tempfile
                >>> from pathlib import Path
                >>> import geopandas as gpd
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import LazyFeatureCollection
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": [1, 2, 3]},
                ...     geometry=[Point(i, i) for i in range(3)],
                ...     crs="EPSG:4326",
                ... )
                >>> d = Path(tempfile.mkdtemp())
                >>> p = d / "pts.geojson"
                >>> gdf.to_file(p, driver="GeoJSON")
                >>> lfc = LazyFeatureCollection.read_file(str(p), npartitions=1)
                >>> lfc.npartitions
                1
                >>> len(lfc.compute())
                3

                ```
        """
        from pyramids.feature import FeatureCollection

        result = FeatureCollection.read_file(
            path,
            backend="dask",
            npartitions=npartitions,
            chunksize=chunksize,
            **kwargs,
        )
        return result

    @property
    def epsg(self) -> int | None:
        """EPSG code of the CRS, or `None` when the CRS is unset.

        Cheap — reads the cached pyproj CRS attached to the
        dask-geopandas frame and calls `.to_epsg()`. No graph
        materialisation.

        Examples:
            - Inspect the EPSG of a lazy FC built from a WGS84 GDF:
                ```python
                >>> import geopandas as gpd
                >>> import dask_geopandas as dg
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import LazyFeatureCollection
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": [1]},
                ...     geometry=[Point(0, 0)],
                ...     crs="EPSG:4326",
                ... )
                >>> lfc = LazyFeatureCollection.from_dask_gdf(
                ...     dg.from_geopandas(gdf, npartitions=1)
                ... )
                >>> lfc.epsg
                4326

                ```
        """
        crs = self.crs
        result = None if crs is None else crs.to_epsg()
        return result

    def compute_total_bounds(self) -> Any:
        """Materialise :attr:`total_bounds` via an explicit `.compute()` call.

        :attr:`total_bounds` on a
        :class:`dask_geopandas.GeoDataFrame` is a lazy dask Scalar.
        Most consumers who want concrete numbers today wrote
        `lfc.total_bounds.compute()` — this helper gives them a
        single-line, self-documenting equivalent that also makes the
        compute-cost explicit in the method name.

        Returns:
            numpy.ndarray: `[minx, miny, maxx, maxy]` as a
            4-element 1-D array — the exact shape
            :class:`geopandas.GeoDataFrame.total_bounds` returns.

        Examples:
            - Force the reduction and destructure into named values:
                ```python
                >>> import geopandas as gpd
                >>> import dask_geopandas as dg
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import LazyFeatureCollection
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": [1, 2]},
                ...     geometry=[Point(0, 0), Point(10, 20)],
                ...     crs="EPSG:4326",
                ... )
                >>> lfc = LazyFeatureCollection.from_dask_gdf(
                ...     dg.from_geopandas(gdf, npartitions=1)
                ... )
                >>> xmin, ymin, xmax, ymax = lfc.compute_total_bounds()
                >>> float(xmin), float(ymax)
                (0.0, 20.0)

                ```
        """
        return self.total_bounds.compute()

    def plot(self, *args: Any, **kwargs: Any) -> Any:
        """No lazy plot path; materialize first.

        Raises:
            NotImplementedError: Always. Call `.compute().plot(...)` to
                materialize before plotting.

        Examples:
            - Calling `.plot` directly raises with an actionable hint:
                ```python
                >>> import geopandas as gpd
                >>> import dask_geopandas as dg
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import LazyFeatureCollection
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": [1]},
                ...     geometry=[Point(0, 0)],
                ...     crs="EPSG:4326",
                ... )
                >>> lfc = LazyFeatureCollection.from_dask_gdf(
                ...     dg.from_geopandas(gdf, npartitions=1)
                ... )
                >>> try:
                ...     lfc.plot()
                ... except NotImplementedError as exc:
                ...     "compute().plot" in str(exc)
                True

                ```
        """
        raise NotImplementedError(
            "LazyFeatureCollection.plot is not supported — call "
            ".compute().plot(...) to materialize first."
        )

    def compute(self, **kwargs: Any) -> FeatureCollection:
        """Materialize the graph and return an eager :class:`FeatureCollection`.

        The `from pyramids.feature import FeatureCollection`
        import below is inline by necessity — `collection.py` imports
        this module from inside its dask branch, so a top-of-file import
        here would form a cycle. Per `CLAUDE.md`, circular-import
        breaks are the second accepted exception to the no-inline-imports
        rule.

        Args:
            **kwargs: Forwarded to
                :meth:`dask_geopandas.GeoDataFrame.compute` (e.g.
                `scheduler="processes"`).

        Returns:
            FeatureCollection: an eager wrapper around the materialized
            :class:`geopandas.GeoDataFrame`.

        Examples:
            - Compute a two-partition lazy frame back to eager form:
                ```python
                >>> import geopandas as gpd
                >>> import dask_geopandas as dg
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import (
                ...     FeatureCollection, LazyFeatureCollection,
                ... )
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": [1, 2, 3, 4]},
                ...     geometry=[Point(i, i) for i in range(4)],
                ...     crs="EPSG:4326",
                ... )
                >>> lfc = LazyFeatureCollection.from_dask_gdf(
                ...     dg.from_geopandas(gdf, npartitions=2)
                ... )
                >>> eager = lfc.compute()
                >>> len(eager)
                4
                >>> eager.epsg
                4326

                ```
        """
        from pyramids.feature import FeatureCollection

        gdf = super().compute(**kwargs)
        result = FeatureCollection(gdf)
        return result

    def persist(self, **kwargs: Any) -> LazyFeatureCollection:
        """Persist partitions in worker memory; keep the FC lazy.

        Args:
            **kwargs: Forwarded to
                :meth:`dask_geopandas.GeoDataFrame.persist`.

        Returns:
            LazyFeatureCollection: A new lazy FC whose graph has been
            materialized into worker memory.

        Examples:
            - Persist and confirm the result is still lazy:
                ```python
                >>> import geopandas as gpd
                >>> import dask_geopandas as dg
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import LazyFeatureCollection
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": [1, 2]},
                ...     geometry=[Point(0, 0), Point(1, 1)],
                ...     crs="EPSG:4326",
                ... )
                >>> lfc = LazyFeatureCollection.from_dask_gdf(
                ...     dg.from_geopandas(gdf, npartitions=2)
                ... )
                >>> persisted = lfc.persist()
                >>> isinstance(persisted, LazyFeatureCollection)
                True
                >>> persisted.npartitions
                2

                ```
        """
        persisted = super().persist(**kwargs)
        result = type(self).from_dask_gdf(persisted)
        return result

    def spatial_shuffle(
        self,
        by: str = "hilbert",
        level: int = 16,
        *,
        npartitions: int | None = None,
        divisions: Any = None,
    ) -> LazyFeatureCollection:
        """Spatially sort rows via a space-filling curve.

        Thin override of :meth:`dask_geopandas.GeoDataFrame.spatial_shuffle`
        that rewraps the result as a :class:`LazyFeatureCollection`.
        Populates :attr:`spatial_partitions`, enabling partition-pruned
        :meth:`sjoin` on the result.

        Args:
            by: One of `"hilbert"`, `"morton"`, or `"geohash"`.
            level: Curve resolution; default 16.
            npartitions: Optional output partition count.
            divisions: Optional explicit division boundaries.

        Returns:
            LazyFeatureCollection: A new lazy FC with `spatial_partitions`
            populated.

        Examples:
            - Shuffle a two-partition frame and confirm bboxes are set:
                ```python
                >>> import geopandas as gpd
                >>> import dask_geopandas as dg
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import LazyFeatureCollection
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": list(range(8))},
                ...     geometry=[Point(i, i) for i in range(8)],
                ...     crs="EPSG:4326",
                ... )
                >>> lfc = LazyFeatureCollection.from_dask_gdf(
                ...     dg.from_geopandas(gdf, npartitions=2)
                ... )
                >>> shuffled = lfc.spatial_shuffle()
                >>> shuffled.spatial_partitions is not None
                True

                ```
        """
        kwargs: dict[str, Any] = {}
        if npartitions is not None:
            kwargs["npartitions"] = npartitions
        if divisions is not None:
            kwargs["divisions"] = divisions
        shuffled = super().spatial_shuffle(by=by, level=level, **kwargs)
        result = type(self).from_dask_gdf(shuffled)
        return result

    def to_file(self, path: Any, *args: Any, **kwargs: Any) -> None:
        """No lazy OGR write path exists; raise with an actionable message.

        Raises:
            NotImplementedError: Always. dask-geopandas has no lazy OGR
                write path for GeoJSON / Shapefile / GeoPackage. Call
                `.compute().to_file(path)` to materialize first, or
                use `to_parquet` which IS lazy.

        Examples:
            - The hint at the raise site points to the supported paths:
                ```python
                >>> import geopandas as gpd
                >>> import dask_geopandas as dg
                >>> from shapely.geometry import Point
                >>> from pyramids.feature import LazyFeatureCollection
                >>> gdf = gpd.GeoDataFrame(
                ...     {"v": [1]},
                ...     geometry=[Point(0, 0)],
                ...     crs="EPSG:4326",
                ... )
                >>> lfc = LazyFeatureCollection.from_dask_gdf(
                ...     dg.from_geopandas(gdf, npartitions=1)
                ... )
                >>> try:
                ...     lfc.to_file("out.geojson")
                ... except NotImplementedError as exc:
                ...     "compute().to_file" in str(exc)
                True

                ```
        """
        raise NotImplementedError(
            "LazyFeatureCollection.to_file is not supported — "
            "dask-geopandas has no lazy OGR write path. Call "
            ".compute().to_file(path) to materialize first, or "
            "write via read_parquet + fc.to_parquet(path) which IS lazy."
        )

    def to_parquet(self, path: Any, *args: Any, **kwargs: Any) -> None:
        """Write the lazy frame to GeoParquet (the one genuinely-lazy writer).

        explicit wrapper around
        :meth:`dask_geopandas.GeoDataFrame.to_parquet`. The parent
        returns a :class:`dask.delayed.Delayed` (or `None` when the
        call is implicitly computed), which leaks the dask detail into
        user code and breaks the pyramids convention that `to_*`
        writers return `None`. This override normalises the contract:

        * The call blocks until every partition has been written.
        * Return is always `None` — matches
          :meth:`FeatureCollection.to_parquet` and
          :meth:`LazyFeatureCollection.to_file` (the raising stub).
        * All other kwargs (`compression=`, `write_index=`,
          `storage_options=`) forward to the parent.

        Args:
            path: Destination path or directory. Cloud URLs (`s3://`,
                `gs://`, `az://`) work via `storage_options`.
            *args: Forwarded to
                :meth:`dask_geopandas.GeoDataFrame.to_parquet`.
            **kwargs: Forwarded to
                :meth:`dask_geopandas.GeoDataFrame.to_parquet`.
                `compute=True` is forced; passing `compute=False`
                raises :class:`ValueError` because the pyramids API
                contract is "`to_*` always writes, never defers".

        Raises:
            ValueError: If `compute=False` is supplied. Use the
                parent's API directly if you need a Delayed.

        Examples:
            - Round-trip a lazy FC through GeoParquet:
                ```python
                >>> import tempfile  # doctest: +SKIP
                >>> from pathlib import Path  # doctest: +SKIP
                >>> import geopandas as gpd  # doctest: +SKIP
                >>> import dask_geopandas as dg  # doctest: +SKIP
                >>> from shapely.geometry import Point  # doctest: +SKIP
                >>> from pyramids.feature import LazyFeatureCollection  # doctest: +SKIP
                >>> d = Path(tempfile.mkdtemp())  # doctest: +SKIP
                >>> gdf = gpd.GeoDataFrame(
                ...     {"id": [1, 2]},
                ...     geometry=[Point(0, 0), Point(1, 1)],
                ...     crs="EPSG:4326",
                ... )  # doctest: +SKIP
                >>> lfc = LazyFeatureCollection.from_dask_gdf(
                ...     dg.from_geopandas(gdf, npartitions=1)
                ... )  # doctest: +SKIP
                >>> lfc.to_parquet(d / "out.parquet")  # doctest: +SKIP

                ```
        """
        if kwargs.get("compute") is False:
            raise ValueError(
                "LazyFeatureCollection.to_parquet always writes — "
                "passing compute=False is not supported. Use "
                "self._data.to_parquet(...) or go through the "
                "dask_geopandas parent API directly if you need a "
                "Delayed."
            )
        kwargs["compute"] = True
        # dask_geopandas writes through fsspec, which resolves the scheme itself
        # and does not register every spelling GDAL accepts (#918).
        super().to_parquet(to_fsspec_url(str(path)), *args, **kwargs)

    def __repr__(self) -> str:
        """Pyramids-branded repr; avoids the generic Dask DataFrame one."""
        return (
            f"LazyFeatureCollection(npartitions={self.npartitions}, "
            f"columns={list(self.columns)}, crs={self.crs})"
        )

epsg property #

EPSG code of the CRS, or None when the CRS is unset.

Cheap — reads the cached pyproj CRS attached to the dask-geopandas frame and calls .to_epsg(). No graph materialisation.

Examples:

  • Inspect the EPSG of a lazy FC built from a WGS84 GDF:
    >>> import geopandas as gpd
    >>> import dask_geopandas as dg
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import LazyFeatureCollection
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": [1]},
    ...     geometry=[Point(0, 0)],
    ...     crs="EPSG:4326",
    ... )
    >>> lfc = LazyFeatureCollection.from_dask_gdf(
    ...     dg.from_geopandas(gdf, npartitions=1)
    ... )
    >>> lfc.epsg
    4326
    

__getattribute__(name) #

Return a class-swapped view of every inherited method's result.

dask-geopandas inherits from dask-expr and does not honour pandas' classic _constructor hook. Methods like to_crs, clip, sjoin, copy, drop_duplicates go through map_partitions with meta inference and produce a plain :class:dask_geopandas.GeoDataFrame, silently dropping the :class:LazyFeatureCollection subclass. This hook wraps every public callable so that a :class:dask_geopandas.GeoDataFrame result is rebranded back to the subclass before it reaches the caller. Private names (_-prefixed) are passed through unchanged to keep dask-expr internals — meta inference, name caches, partition probing — on the hot path they expect.

Source code in src/pyramids_lazy/_lazy_collection.py
def __getattribute__(self, name: str) -> Any:
    """Return a class-swapped view of every inherited method's result.

    dask-geopandas inherits from dask-expr and does not honour pandas'
    classic `_constructor` hook. Methods like `to_crs`, `clip`,
    `sjoin`, `copy`, `drop_duplicates` go through
    `map_partitions` with meta inference and produce a plain
    :class:`dask_geopandas.GeoDataFrame`, silently dropping the
    :class:`LazyFeatureCollection` subclass. This hook wraps every
    public callable so that a :class:`dask_geopandas.GeoDataFrame`
    result is rebranded back to the subclass before it reaches the
    caller. Private names (`_`-prefixed) are passed through
    unchanged to keep dask-expr internals — meta inference, name
    caches, partition probing — on the hot path they expect.
    """
    attr = object.__getattribute__(self, name)
    if name.startswith("_") or not callable(attr):
        return attr
    cls = type(self)

    @functools.wraps(attr)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        result = attr(*args, **kwargs)
        if isinstance(result, dask_geopandas.GeoDataFrame) and not isinstance(
            result,
            cls,
        ):
            result = cls.from_dask_gdf(result)
        elif isinstance(result, geopandas.GeoDataFrame) and not isinstance(
            result,
            geopandas.GeoSeries,
        ):
            from pyramids.feature import FeatureCollection

            # Skip the wrap when the method (e.g. an overridden `compute`) already
            # returned a FeatureCollection, avoiding a redundant double-wrap (ARC-63).
            if not isinstance(result, FeatureCollection):
                result = FeatureCollection(result)
        return result

    return wrapper

__reduce__() #

Preserve the LazyFeatureCollection class across pickle round-trips.

from_dask_gdf uses result.__class__ = cls to rebind the concrete class. The parent's default __reduce__ reconstructs with the base :class:dask_geopandas.GeoDataFrame, silently dropping the subclass on unpickle. Wrapping super's reduce tuple in a module-level trampoline re-applies the class swap.

Source code in src/pyramids_lazy/_lazy_collection.py
def __reduce__(self):
    """Preserve the LazyFeatureCollection class across pickle round-trips.

    `from_dask_gdf` uses `result.__class__ = cls` to rebind the
    concrete class. The parent's default `__reduce__` reconstructs
    with the base :class:`dask_geopandas.GeoDataFrame`, silently
    dropping the subclass on unpickle. Wrapping super's reduce tuple
    in a module-level trampoline re-applies the class swap.
    """
    return (_rebuild_lazy_fc, (super().__reduce__(),))

__repr__() #

Pyramids-branded repr; avoids the generic Dask DataFrame one.

Source code in src/pyramids_lazy/_lazy_collection.py
def __repr__(self) -> str:
    """Pyramids-branded repr; avoids the generic Dask DataFrame one."""
    return (
        f"LazyFeatureCollection(npartitions={self.npartitions}, "
        f"columns={list(self.columns)}, crs={self.crs})"
    )

compute(**kwargs) #

Materialize the graph and return an eager :class:FeatureCollection.

The from pyramids.feature import FeatureCollection import below is inline by necessity — collection.py imports this module from inside its dask branch, so a top-of-file import here would form a cycle. Per CLAUDE.md, circular-import breaks are the second accepted exception to the no-inline-imports rule.

Parameters:

Name Type Description Default
**kwargs Any

Forwarded to :meth:dask_geopandas.GeoDataFrame.compute (e.g. scheduler="processes").

{}

Returns:

Name Type Description
FeatureCollection FeatureCollection

an eager wrapper around the materialized

FeatureCollection

class:geopandas.GeoDataFrame.

Examples:

  • Compute a two-partition lazy frame back to eager form:
    >>> import geopandas as gpd
    >>> import dask_geopandas as dg
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import (
    ...     FeatureCollection, LazyFeatureCollection,
    ... )
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": [1, 2, 3, 4]},
    ...     geometry=[Point(i, i) for i in range(4)],
    ...     crs="EPSG:4326",
    ... )
    >>> lfc = LazyFeatureCollection.from_dask_gdf(
    ...     dg.from_geopandas(gdf, npartitions=2)
    ... )
    >>> eager = lfc.compute()
    >>> len(eager)
    4
    >>> eager.epsg
    4326
    
Source code in src/pyramids_lazy/_lazy_collection.py
def compute(self, **kwargs: Any) -> FeatureCollection:
    """Materialize the graph and return an eager :class:`FeatureCollection`.

    The `from pyramids.feature import FeatureCollection`
    import below is inline by necessity — `collection.py` imports
    this module from inside its dask branch, so a top-of-file import
    here would form a cycle. Per `CLAUDE.md`, circular-import
    breaks are the second accepted exception to the no-inline-imports
    rule.

    Args:
        **kwargs: Forwarded to
            :meth:`dask_geopandas.GeoDataFrame.compute` (e.g.
            `scheduler="processes"`).

    Returns:
        FeatureCollection: an eager wrapper around the materialized
        :class:`geopandas.GeoDataFrame`.

    Examples:
        - Compute a two-partition lazy frame back to eager form:
            ```python
            >>> import geopandas as gpd
            >>> import dask_geopandas as dg
            >>> from shapely.geometry import Point
            >>> from pyramids.feature import (
            ...     FeatureCollection, LazyFeatureCollection,
            ... )
            >>> gdf = gpd.GeoDataFrame(
            ...     {"v": [1, 2, 3, 4]},
            ...     geometry=[Point(i, i) for i in range(4)],
            ...     crs="EPSG:4326",
            ... )
            >>> lfc = LazyFeatureCollection.from_dask_gdf(
            ...     dg.from_geopandas(gdf, npartitions=2)
            ... )
            >>> eager = lfc.compute()
            >>> len(eager)
            4
            >>> eager.epsg
            4326

            ```
    """
    from pyramids.feature import FeatureCollection

    gdf = super().compute(**kwargs)
    result = FeatureCollection(gdf)
    return result

compute_total_bounds() #

Materialise :attr:total_bounds via an explicit .compute() call.

:attr:total_bounds on a :class:dask_geopandas.GeoDataFrame is a lazy dask Scalar. Most consumers who want concrete numbers today wrote lfc.total_bounds.compute() — this helper gives them a single-line, self-documenting equivalent that also makes the compute-cost explicit in the method name.

Returns:

Type Description
Any

numpy.ndarray: [minx, miny, maxx, maxy] as a

Any

4-element 1-D array — the exact shape

Any

class:geopandas.GeoDataFrame.total_bounds returns.

Examples:

  • Force the reduction and destructure into named values:
    >>> import geopandas as gpd
    >>> import dask_geopandas as dg
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import LazyFeatureCollection
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": [1, 2]},
    ...     geometry=[Point(0, 0), Point(10, 20)],
    ...     crs="EPSG:4326",
    ... )
    >>> lfc = LazyFeatureCollection.from_dask_gdf(
    ...     dg.from_geopandas(gdf, npartitions=1)
    ... )
    >>> xmin, ymin, xmax, ymax = lfc.compute_total_bounds()
    >>> float(xmin), float(ymax)
    (0.0, 20.0)
    
Source code in src/pyramids_lazy/_lazy_collection.py
def compute_total_bounds(self) -> Any:
    """Materialise :attr:`total_bounds` via an explicit `.compute()` call.

    :attr:`total_bounds` on a
    :class:`dask_geopandas.GeoDataFrame` is a lazy dask Scalar.
    Most consumers who want concrete numbers today wrote
    `lfc.total_bounds.compute()` — this helper gives them a
    single-line, self-documenting equivalent that also makes the
    compute-cost explicit in the method name.

    Returns:
        numpy.ndarray: `[minx, miny, maxx, maxy]` as a
        4-element 1-D array — the exact shape
        :class:`geopandas.GeoDataFrame.total_bounds` returns.

    Examples:
        - Force the reduction and destructure into named values:
            ```python
            >>> import geopandas as gpd
            >>> import dask_geopandas as dg
            >>> from shapely.geometry import Point
            >>> from pyramids.feature import LazyFeatureCollection
            >>> gdf = gpd.GeoDataFrame(
            ...     {"v": [1, 2]},
            ...     geometry=[Point(0, 0), Point(10, 20)],
            ...     crs="EPSG:4326",
            ... )
            >>> lfc = LazyFeatureCollection.from_dask_gdf(
            ...     dg.from_geopandas(gdf, npartitions=1)
            ... )
            >>> xmin, ymin, xmax, ymax = lfc.compute_total_bounds()
            >>> float(xmin), float(ymax)
            (0.0, 20.0)

            ```
    """
    return self.total_bounds.compute()

from_dask_gdf(dask_gdf) classmethod #

Wrap an existing :class:dask_geopandas.GeoDataFrame as a LazyFC.

This is the canonical construction path for code that already holds a pre-built :class:dask_geopandas.GeoDataFrame (for example, from :func:dask_geopandas.from_geopandas or a third-party reader) and wants to use it through the pyramids type system.

Implementation uses class-swap (copy() + __class__ assignment) rather than a four-arg reconstruction, because (dask, _name, _meta, divisions) is private dask.dataframe API that shifted between dask-expr and legacy. Class-swap relies only on Python's object model and survives upstream churn. The invariant "LazyFeatureCollection adds no extra instance state beyond :class:dask_geopandas.GeoDataFrame" is pinned by :func:tests.feature.test_lazy_feature_collection.test_from_dask_gdf_preserves_state.

Parameters:

Name Type Description Default
dask_gdf Any

Pre-built dask_geopandas.GeoDataFrame to wrap.

required

Returns:

Name Type Description
LazyFeatureCollection LazyFeatureCollection

A view over dask_gdf whose

LazyFeatureCollection

__class__ has been rebound to LazyFeatureCollection.

LazyFeatureCollection

The task graph, partition names, metadata, and divisions

LazyFeatureCollection

are unchanged — only the concrete class is swapped.

Examples:

  • Wrap a fresh dask_geopandas frame:
    >>> import geopandas as gpd
    >>> import dask_geopandas as dg
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import LazyFeatureCollection
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": [1, 2]},
    ...     geometry=[Point(0, 0), Point(1, 1)],
    ...     crs="EPSG:4326",
    ... )
    >>> ddf = dg.from_geopandas(gdf, npartitions=1)
    >>> lfc = LazyFeatureCollection.from_dask_gdf(ddf)
    >>> lfc.npartitions
    1
    >>> lfc.epsg
    4326
    
Source code in src/pyramids_lazy/_lazy_collection.py
@classmethod
def from_dask_gdf(cls, dask_gdf: Any) -> LazyFeatureCollection:
    """Wrap an existing :class:`dask_geopandas.GeoDataFrame` as a LazyFC.

    This is the canonical construction path for code that already holds
    a pre-built :class:`dask_geopandas.GeoDataFrame` (for example,
    from :func:`dask_geopandas.from_geopandas` or a third-party reader)
    and wants to use it through the pyramids type system.

    Implementation uses class-swap (`copy()` + `__class__`
    assignment) rather than a four-arg reconstruction, because
    `(dask, _name, _meta, divisions)` is private dask.dataframe API
    that shifted between dask-expr and legacy. Class-swap relies only
    on Python's object model and survives upstream churn. The
    invariant "`LazyFeatureCollection` adds no extra instance state
    beyond :class:`dask_geopandas.GeoDataFrame`" is pinned by
    :func:`tests.feature.test_lazy_feature_collection.test_from_dask_gdf_preserves_state`.

    Args:
        dask_gdf: Pre-built `dask_geopandas.GeoDataFrame` to wrap.

    Returns:
        LazyFeatureCollection: A view over `dask_gdf` whose
        `__class__` has been rebound to LazyFeatureCollection.
        The task graph, partition names, metadata, and divisions
        are unchanged — only the concrete class is swapped.

    Examples:
        - Wrap a fresh dask_geopandas frame:
            ```python
            >>> import geopandas as gpd
            >>> import dask_geopandas as dg
            >>> from shapely.geometry import Point
            >>> from pyramids.feature import LazyFeatureCollection
            >>> gdf = gpd.GeoDataFrame(
            ...     {"v": [1, 2]},
            ...     geometry=[Point(0, 0), Point(1, 1)],
            ...     crs="EPSG:4326",
            ... )
            >>> ddf = dg.from_geopandas(gdf, npartitions=1)
            >>> lfc = LazyFeatureCollection.from_dask_gdf(ddf)
            >>> lfc.npartitions
            1
            >>> lfc.epsg
            4326

            ```
    """
    result = dask_gdf.copy()
    result.__class__ = cls
    return cast("LazyFeatureCollection", result)

persist(**kwargs) #

Persist partitions in worker memory; keep the FC lazy.

Parameters:

Name Type Description Default
**kwargs Any

Forwarded to :meth:dask_geopandas.GeoDataFrame.persist.

{}

Returns:

Name Type Description
LazyFeatureCollection LazyFeatureCollection

A new lazy FC whose graph has been

LazyFeatureCollection

materialized into worker memory.

Examples:

  • Persist and confirm the result is still lazy:
    >>> import geopandas as gpd
    >>> import dask_geopandas as dg
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import LazyFeatureCollection
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": [1, 2]},
    ...     geometry=[Point(0, 0), Point(1, 1)],
    ...     crs="EPSG:4326",
    ... )
    >>> lfc = LazyFeatureCollection.from_dask_gdf(
    ...     dg.from_geopandas(gdf, npartitions=2)
    ... )
    >>> persisted = lfc.persist()
    >>> isinstance(persisted, LazyFeatureCollection)
    True
    >>> persisted.npartitions
    2
    
Source code in src/pyramids_lazy/_lazy_collection.py
def persist(self, **kwargs: Any) -> LazyFeatureCollection:
    """Persist partitions in worker memory; keep the FC lazy.

    Args:
        **kwargs: Forwarded to
            :meth:`dask_geopandas.GeoDataFrame.persist`.

    Returns:
        LazyFeatureCollection: A new lazy FC whose graph has been
        materialized into worker memory.

    Examples:
        - Persist and confirm the result is still lazy:
            ```python
            >>> import geopandas as gpd
            >>> import dask_geopandas as dg
            >>> from shapely.geometry import Point
            >>> from pyramids.feature import LazyFeatureCollection
            >>> gdf = gpd.GeoDataFrame(
            ...     {"v": [1, 2]},
            ...     geometry=[Point(0, 0), Point(1, 1)],
            ...     crs="EPSG:4326",
            ... )
            >>> lfc = LazyFeatureCollection.from_dask_gdf(
            ...     dg.from_geopandas(gdf, npartitions=2)
            ... )
            >>> persisted = lfc.persist()
            >>> isinstance(persisted, LazyFeatureCollection)
            True
            >>> persisted.npartitions
            2

            ```
    """
    persisted = super().persist(**kwargs)
    result = type(self).from_dask_gdf(persisted)
    return result

plot(*args, **kwargs) #

No lazy plot path; materialize first.

Raises:

Type Description
NotImplementedError

Always. Call .compute().plot(...) to materialize before plotting.

Examples:

  • Calling .plot directly raises with an actionable hint:
    >>> import geopandas as gpd
    >>> import dask_geopandas as dg
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import LazyFeatureCollection
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": [1]},
    ...     geometry=[Point(0, 0)],
    ...     crs="EPSG:4326",
    ... )
    >>> lfc = LazyFeatureCollection.from_dask_gdf(
    ...     dg.from_geopandas(gdf, npartitions=1)
    ... )
    >>> try:
    ...     lfc.plot()
    ... except NotImplementedError as exc:
    ...     "compute().plot" in str(exc)
    True
    
Source code in src/pyramids_lazy/_lazy_collection.py
def plot(self, *args: Any, **kwargs: Any) -> Any:
    """No lazy plot path; materialize first.

    Raises:
        NotImplementedError: Always. Call `.compute().plot(...)` to
            materialize before plotting.

    Examples:
        - Calling `.plot` directly raises with an actionable hint:
            ```python
            >>> import geopandas as gpd
            >>> import dask_geopandas as dg
            >>> from shapely.geometry import Point
            >>> from pyramids.feature import LazyFeatureCollection
            >>> gdf = gpd.GeoDataFrame(
            ...     {"v": [1]},
            ...     geometry=[Point(0, 0)],
            ...     crs="EPSG:4326",
            ... )
            >>> lfc = LazyFeatureCollection.from_dask_gdf(
            ...     dg.from_geopandas(gdf, npartitions=1)
            ... )
            >>> try:
            ...     lfc.plot()
            ... except NotImplementedError as exc:
            ...     "compute().plot" in str(exc)
            True

            ```
    """
    raise NotImplementedError(
        "LazyFeatureCollection.plot is not supported — call "
        ".compute().plot(...) to materialize first."
    )

read_file(path, *, npartitions=None, chunksize=None, **kwargs) classmethod #

Construct a LazyFC from a vector file.

Satisfies the :class:~pyramids.base.protocols.SpatialObject protocol's read_file classmethod requirement. Delegates to :meth:FeatureCollection.read_file with backend='dask'.

The import of :class:FeatureCollection is inline by necessity — :mod:pyramids.feature.collection imports this module from inside its dask branch, so a top-of-file import here would form a cycle. Per CLAUDE.md, circular-import breaks are an accepted exception to the no-inline-imports rule.

Parameters:

Name Type Description Default
path str | Path

Path to a vector file GDAL/OGR can open (GeoJSON, Shapefile, GeoPackage, FlatGeobuf, …).

required
npartitions int | None

Target number of dask partitions. Mutually exclusive with chunksize.

None
chunksize int | None

Target rows per partition. Mutually exclusive with npartitions.

None
**kwargs Any

Forwarded to :meth:FeatureCollection.read_file. Filter kwargs (bbox / mask / rows / columns / where / layer) are rejected because dask-geopandas has no pushdown for them.

{}

Returns:

Name Type Description
LazyFeatureCollection LazyFeatureCollection

A new lazy FC.

Examples:

  • Read a small GeoJSON as a lazy FC via the classmethod:
    >>> import tempfile
    >>> from pathlib import Path
    >>> import geopandas as gpd
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import LazyFeatureCollection
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": [1, 2, 3]},
    ...     geometry=[Point(i, i) for i in range(3)],
    ...     crs="EPSG:4326",
    ... )
    >>> d = Path(tempfile.mkdtemp())
    >>> p = d / "pts.geojson"
    >>> gdf.to_file(p, driver="GeoJSON")
    >>> lfc = LazyFeatureCollection.read_file(str(p), npartitions=1)
    >>> lfc.npartitions
    1
    >>> len(lfc.compute())
    3
    
Source code in src/pyramids_lazy/_lazy_collection.py
@classmethod
def read_file(
    cls,
    path: str | Path,
    *,
    npartitions: int | None = None,
    chunksize: int | None = None,
    **kwargs: Any,
) -> LazyFeatureCollection:
    """Construct a LazyFC from a vector file.

    Satisfies the :class:`~pyramids.base.protocols.SpatialObject`
    protocol's `read_file` classmethod requirement. Delegates to
    :meth:`FeatureCollection.read_file` with `backend='dask'`.

    The import of :class:`FeatureCollection` is inline by
    necessity — :mod:`pyramids.feature.collection` imports this module
    from inside its dask branch, so a top-of-file import here would
    form a cycle. Per `CLAUDE.md`, circular-import breaks are an
    accepted exception to the no-inline-imports rule.

    Args:
        path: Path to a vector file GDAL/OGR can open (GeoJSON,
            Shapefile, GeoPackage, FlatGeobuf, …).
        npartitions: Target number of dask partitions. Mutually
            exclusive with `chunksize`.
        chunksize: Target rows per partition. Mutually exclusive
            with `npartitions`.
        **kwargs: Forwarded to :meth:`FeatureCollection.read_file`.
            Filter kwargs (`bbox` / `mask` / `rows` /
            `columns` / `where` / `layer`) are rejected
            because dask-geopandas has no pushdown for them.

    Returns:
        LazyFeatureCollection: A new lazy FC.

    Examples:
        - Read a small GeoJSON as a lazy FC via the classmethod:
            ```python
            >>> import tempfile
            >>> from pathlib import Path
            >>> import geopandas as gpd
            >>> from shapely.geometry import Point
            >>> from pyramids.feature import LazyFeatureCollection
            >>> gdf = gpd.GeoDataFrame(
            ...     {"v": [1, 2, 3]},
            ...     geometry=[Point(i, i) for i in range(3)],
            ...     crs="EPSG:4326",
            ... )
            >>> d = Path(tempfile.mkdtemp())
            >>> p = d / "pts.geojson"
            >>> gdf.to_file(p, driver="GeoJSON")
            >>> lfc = LazyFeatureCollection.read_file(str(p), npartitions=1)
            >>> lfc.npartitions
            1
            >>> len(lfc.compute())
            3

            ```
    """
    from pyramids.feature import FeatureCollection

    result = FeatureCollection.read_file(
        path,
        backend="dask",
        npartitions=npartitions,
        chunksize=chunksize,
        **kwargs,
    )
    return result

spatial_shuffle(by='hilbert', level=16, *, npartitions=None, divisions=None) #

Spatially sort rows via a space-filling curve.

Thin override of :meth:dask_geopandas.GeoDataFrame.spatial_shuffle that rewraps the result as a :class:LazyFeatureCollection. Populates :attr:spatial_partitions, enabling partition-pruned :meth:sjoin on the result.

Parameters:

Name Type Description Default
by str

One of "hilbert", "morton", or "geohash".

'hilbert'
level int

Curve resolution; default 16.

16
npartitions int | None

Optional output partition count.

None
divisions Any

Optional explicit division boundaries.

None

Returns:

Name Type Description
LazyFeatureCollection LazyFeatureCollection

A new lazy FC with spatial_partitions

LazyFeatureCollection

populated.

Examples:

  • Shuffle a two-partition frame and confirm bboxes are set:
    >>> import geopandas as gpd
    >>> import dask_geopandas as dg
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import LazyFeatureCollection
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": list(range(8))},
    ...     geometry=[Point(i, i) for i in range(8)],
    ...     crs="EPSG:4326",
    ... )
    >>> lfc = LazyFeatureCollection.from_dask_gdf(
    ...     dg.from_geopandas(gdf, npartitions=2)
    ... )
    >>> shuffled = lfc.spatial_shuffle()
    >>> shuffled.spatial_partitions is not None
    True
    
Source code in src/pyramids_lazy/_lazy_collection.py
def spatial_shuffle(
    self,
    by: str = "hilbert",
    level: int = 16,
    *,
    npartitions: int | None = None,
    divisions: Any = None,
) -> LazyFeatureCollection:
    """Spatially sort rows via a space-filling curve.

    Thin override of :meth:`dask_geopandas.GeoDataFrame.spatial_shuffle`
    that rewraps the result as a :class:`LazyFeatureCollection`.
    Populates :attr:`spatial_partitions`, enabling partition-pruned
    :meth:`sjoin` on the result.

    Args:
        by: One of `"hilbert"`, `"morton"`, or `"geohash"`.
        level: Curve resolution; default 16.
        npartitions: Optional output partition count.
        divisions: Optional explicit division boundaries.

    Returns:
        LazyFeatureCollection: A new lazy FC with `spatial_partitions`
        populated.

    Examples:
        - Shuffle a two-partition frame and confirm bboxes are set:
            ```python
            >>> import geopandas as gpd
            >>> import dask_geopandas as dg
            >>> from shapely.geometry import Point
            >>> from pyramids.feature import LazyFeatureCollection
            >>> gdf = gpd.GeoDataFrame(
            ...     {"v": list(range(8))},
            ...     geometry=[Point(i, i) for i in range(8)],
            ...     crs="EPSG:4326",
            ... )
            >>> lfc = LazyFeatureCollection.from_dask_gdf(
            ...     dg.from_geopandas(gdf, npartitions=2)
            ... )
            >>> shuffled = lfc.spatial_shuffle()
            >>> shuffled.spatial_partitions is not None
            True

            ```
    """
    kwargs: dict[str, Any] = {}
    if npartitions is not None:
        kwargs["npartitions"] = npartitions
    if divisions is not None:
        kwargs["divisions"] = divisions
    shuffled = super().spatial_shuffle(by=by, level=level, **kwargs)
    result = type(self).from_dask_gdf(shuffled)
    return result

to_file(path, *args, **kwargs) #

No lazy OGR write path exists; raise with an actionable message.

Raises:

Type Description
NotImplementedError

Always. dask-geopandas has no lazy OGR write path for GeoJSON / Shapefile / GeoPackage. Call .compute().to_file(path) to materialize first, or use to_parquet which IS lazy.

Examples:

  • The hint at the raise site points to the supported paths:
    >>> import geopandas as gpd
    >>> import dask_geopandas as dg
    >>> from shapely.geometry import Point
    >>> from pyramids.feature import LazyFeatureCollection
    >>> gdf = gpd.GeoDataFrame(
    ...     {"v": [1]},
    ...     geometry=[Point(0, 0)],
    ...     crs="EPSG:4326",
    ... )
    >>> lfc = LazyFeatureCollection.from_dask_gdf(
    ...     dg.from_geopandas(gdf, npartitions=1)
    ... )
    >>> try:
    ...     lfc.to_file("out.geojson")
    ... except NotImplementedError as exc:
    ...     "compute().to_file" in str(exc)
    True
    
Source code in src/pyramids_lazy/_lazy_collection.py
def to_file(self, path: Any, *args: Any, **kwargs: Any) -> None:
    """No lazy OGR write path exists; raise with an actionable message.

    Raises:
        NotImplementedError: Always. dask-geopandas has no lazy OGR
            write path for GeoJSON / Shapefile / GeoPackage. Call
            `.compute().to_file(path)` to materialize first, or
            use `to_parquet` which IS lazy.

    Examples:
        - The hint at the raise site points to the supported paths:
            ```python
            >>> import geopandas as gpd
            >>> import dask_geopandas as dg
            >>> from shapely.geometry import Point
            >>> from pyramids.feature import LazyFeatureCollection
            >>> gdf = gpd.GeoDataFrame(
            ...     {"v": [1]},
            ...     geometry=[Point(0, 0)],
            ...     crs="EPSG:4326",
            ... )
            >>> lfc = LazyFeatureCollection.from_dask_gdf(
            ...     dg.from_geopandas(gdf, npartitions=1)
            ... )
            >>> try:
            ...     lfc.to_file("out.geojson")
            ... except NotImplementedError as exc:
            ...     "compute().to_file" in str(exc)
            True

            ```
    """
    raise NotImplementedError(
        "LazyFeatureCollection.to_file is not supported — "
        "dask-geopandas has no lazy OGR write path. Call "
        ".compute().to_file(path) to materialize first, or "
        "write via read_parquet + fc.to_parquet(path) which IS lazy."
    )

to_parquet(path, *args, **kwargs) #

Write the lazy frame to GeoParquet (the one genuinely-lazy writer).

explicit wrapper around :meth:dask_geopandas.GeoDataFrame.to_parquet. The parent returns a :class:dask.delayed.Delayed (or None when the call is implicitly computed), which leaks the dask detail into user code and breaks the pyramids convention that to_* writers return None. This override normalises the contract:

  • The call blocks until every partition has been written.
  • Return is always None — matches :meth:FeatureCollection.to_parquet and :meth:LazyFeatureCollection.to_file (the raising stub).
  • All other kwargs (compression=, write_index=, storage_options=) forward to the parent.

Parameters:

Name Type Description Default
path Any

Destination path or directory. Cloud URLs (s3://, gs://, az://) work via storage_options.

required
*args Any

Forwarded to :meth:dask_geopandas.GeoDataFrame.to_parquet.

()
**kwargs Any

Forwarded to :meth:dask_geopandas.GeoDataFrame.to_parquet. compute=True is forced; passing compute=False raises :class:ValueError because the pyramids API contract is "to_* always writes, never defers".

{}

Raises:

Type Description
ValueError

If compute=False is supplied. Use the parent's API directly if you need a Delayed.

Examples:

  • Round-trip a lazy FC through GeoParquet:
    >>> import tempfile  # doctest: +SKIP
    >>> from pathlib import Path  # doctest: +SKIP
    >>> import geopandas as gpd  # doctest: +SKIP
    >>> import dask_geopandas as dg  # doctest: +SKIP
    >>> from shapely.geometry import Point  # doctest: +SKIP
    >>> from pyramids.feature import LazyFeatureCollection  # doctest: +SKIP
    >>> d = Path(tempfile.mkdtemp())  # doctest: +SKIP
    >>> gdf = gpd.GeoDataFrame(
    ...     {"id": [1, 2]},
    ...     geometry=[Point(0, 0), Point(1, 1)],
    ...     crs="EPSG:4326",
    ... )  # doctest: +SKIP
    >>> lfc = LazyFeatureCollection.from_dask_gdf(
    ...     dg.from_geopandas(gdf, npartitions=1)
    ... )  # doctest: +SKIP
    >>> lfc.to_parquet(d / "out.parquet")  # doctest: +SKIP
    
Source code in src/pyramids_lazy/_lazy_collection.py
def to_parquet(self, path: Any, *args: Any, **kwargs: Any) -> None:
    """Write the lazy frame to GeoParquet (the one genuinely-lazy writer).

    explicit wrapper around
    :meth:`dask_geopandas.GeoDataFrame.to_parquet`. The parent
    returns a :class:`dask.delayed.Delayed` (or `None` when the
    call is implicitly computed), which leaks the dask detail into
    user code and breaks the pyramids convention that `to_*`
    writers return `None`. This override normalises the contract:

    * The call blocks until every partition has been written.
    * Return is always `None` — matches
      :meth:`FeatureCollection.to_parquet` and
      :meth:`LazyFeatureCollection.to_file` (the raising stub).
    * All other kwargs (`compression=`, `write_index=`,
      `storage_options=`) forward to the parent.

    Args:
        path: Destination path or directory. Cloud URLs (`s3://`,
            `gs://`, `az://`) work via `storage_options`.
        *args: Forwarded to
            :meth:`dask_geopandas.GeoDataFrame.to_parquet`.
        **kwargs: Forwarded to
            :meth:`dask_geopandas.GeoDataFrame.to_parquet`.
            `compute=True` is forced; passing `compute=False`
            raises :class:`ValueError` because the pyramids API
            contract is "`to_*` always writes, never defers".

    Raises:
        ValueError: If `compute=False` is supplied. Use the
            parent's API directly if you need a Delayed.

    Examples:
        - Round-trip a lazy FC through GeoParquet:
            ```python
            >>> import tempfile  # doctest: +SKIP
            >>> from pathlib import Path  # doctest: +SKIP
            >>> import geopandas as gpd  # doctest: +SKIP
            >>> import dask_geopandas as dg  # doctest: +SKIP
            >>> from shapely.geometry import Point  # doctest: +SKIP
            >>> from pyramids.feature import LazyFeatureCollection  # doctest: +SKIP
            >>> d = Path(tempfile.mkdtemp())  # doctest: +SKIP
            >>> gdf = gpd.GeoDataFrame(
            ...     {"id": [1, 2]},
            ...     geometry=[Point(0, 0), Point(1, 1)],
            ...     crs="EPSG:4326",
            ... )  # doctest: +SKIP
            >>> lfc = LazyFeatureCollection.from_dask_gdf(
            ...     dg.from_geopandas(gdf, npartitions=1)
            ... )  # doctest: +SKIP
            >>> lfc.to_parquet(d / "out.parquet")  # doctest: +SKIP

            ```
    """
    if kwargs.get("compute") is False:
        raise ValueError(
            "LazyFeatureCollection.to_parquet always writes — "
            "passing compute=False is not supported. Use "
            "self._data.to_parquet(...) or go through the "
            "dask_geopandas parent API directly if you need a "
            "Delayed."
        )
    kwargs["compute"] = True
    # dask_geopandas writes through fsspec, which resolves the scheme itself
    # and does not register every spelling GDAL accepts (#918).
    super().to_parquet(to_fsspec_url(str(path)), *args, **kwargs)