Add standalone basin module, fix BoundaryStore temp file leaks

Extract basin delineation from watershed.py into its own basin.py
module with a basin() public function. The old basins() stays as a
backward-compatible wrapper. Add basin to __init__.py and both
xarray accessors.

Add BoundarySnapshot to _boundary_store.py -- a read-only in-memory
copy of converged boundary strips. BoundaryStore.snapshot() copies
strip data to plain numpy arrays and closes the underlying memmap
temp files. Apply this pattern across all hydrology dask backends
(flow_accumulation, watershed, fill, stream_order) so temp
directories are cleaned up before the lazy dask result is returned.
Previously, BoundaryStore objects captured in map_blocks closures
kept temp files alive indefinitely.

Author: brendancol

xrspatial/__init__.py

@@ -46,6 +46,7 @@
 from xrspatial.terrain_metrics import tri  # noqa
 from xrspatial.polygonize import polygonize  # noqa
 from xrspatial.viewshed import viewshed  # noqa
+from xrspatial.basin import basin  # noqa
 from xrspatial.watershed import basins  # noqa
 from xrspatial.watershed import watershed  # noqa
 from xrspatial.zonal import apply as zonal_apply  # noqa

xrspatial/_boundary_store.py

@@ -97,8 +97,48 @@ def close(self):
     def __del__(self):
         self.close()
 
+    def snapshot(self):
+        """Return a lightweight in-memory copy and close this store.
+
+        The returned ``BoundarySnapshot`` has the same ``.get()``
+        interface but holds plain numpy arrays instead of memmaps,
+        so no temp files remain referenced.
+        """
+        snap = BoundarySnapshot(self)
+        self.close()
+        return snap
+
     def __enter__(self):
         return self
 
     def __exit__(self, *exc):
         self.close()
+
+
+class BoundarySnapshot:
+    """Read-only in-memory copy of converged boundary strips.
+
+    Created via ``BoundaryStore.snapshot()``; exposes the same
+    ``.get(side, iy, ix)`` interface so callers need no changes.
+    """
+
+    def __init__(self, store):
+        self._cum_x = store._cum_x
+        self._cum_y = store._cum_y
+        # Copy memmap data to plain numpy arrays
+        for name in ('top', 'bottom', 'left', 'right'):
+            src = getattr(store, f'_{name}')
+            setattr(self, f'_{name}', np.array(src))
+
+    def get(self, side, iy, ix):
+        """Return a numpy view of the boundary strip for tile (iy, ix)."""
+        if side == 'top':
+            return self._top[iy, self._cum_x[ix]:self._cum_x[ix + 1]]
+        elif side == 'bottom':
+            return self._bottom[iy, self._cum_x[ix]:self._cum_x[ix + 1]]
+        elif side == 'left':
+            return self._left[ix, self._cum_y[iy]:self._cum_y[iy + 1]]
+        elif side == 'right':
+            return self._right[ix, self._cum_y[iy]:self._cum_y[iy + 1]]
+        else:
+            raise ValueError(f"Unknown side: {side!r}")

xrspatial/accessor.py

@@ -67,6 +67,10 @@ def watershed(self, pour_points, **kwargs):
         from .watershed import watershed
         return watershed(self._obj, pour_points, **kwargs)
 
+    def basin(self, **kwargs):
+        from .basin import basin
+        return basin(self._obj, **kwargs)
+
     def basins(self, **kwargs):
         from .watershed import basins
         return basins(self._obj, **kwargs)
@@ -293,6 +297,10 @@ def watershed(self, pour_points, **kwargs):
         from .watershed import watershed
         return watershed(self._obj, pour_points, **kwargs)
 
+    def basin(self, **kwargs):
+        from .basin import basin
+        return basin(self._obj, **kwargs)
+
     def basins(self, **kwargs):
         from .watershed import basins
         return basins(self._obj, **kwargs)