Merge branch 'forman-82-slice_source_is_cm' into forman-82-slice_source_kwargs

Author: forman

docs/guide.md

@@ -699,7 +699,7 @@ The `SliceSource` methods with special meaning are:
 * `get_dataset()`: a zero-argument method that returns the slice dataset of type 
   `xarray.Dataset`. You must implement this abstract method. 
 * `close()`: perform any resource cleanup tasks 
-  (in zappend < v0.7, the `close` methods was called `dispose`).
+  (in zappend < v0.7, the `close` method was called `dispose`).
 * `__init__()`: optional constructor that receives any arguments passed to the 
   slice source.
 

zappend/api.py

@@ -45,14 +45,22 @@ def zappend(
     This ensures integrity of the  target data cube `target_dir` given
     in `config` or `kwargs`.
 
+    Each slice item in `slices` provides a slice dataset to be appended.
+    The interpretation of a given slice item depends on whether a slice source
+    is configured or not (setting `slice_source`).
+
+    If no slice source is configured, a slice item must be an object of type
+    `str`, `FileObj`, `xarray.Dataset`, or `SliceSource`.
+    If `str` or `FileObj` are used, they are interpreted as local dataset path or
+    dataset URI. If a URI is used, protocol-specific parameters apply, given by the
+    configuration parameter `slice_storage_options`.
+
+    If a slice source is configured, a slice item represents the argument(s) passed
+    to that slice source. Multiple positional arguments can be passed as `list`,
+    multiple keyword arguments as `dict`, and both as a `tuple` of `list` and `dict`.
+
     Args:
-        slices: An iterable that yields slice items. A slice item is
-            either a `str`, `FileObj`, `xarray.Dataset`, `SliceSource`,
-            or represents arguments passed to a configured `slice_source`.
-            If `str` or `FileObj` are used, they are interpreted as
-            local dataset path or dataset URI.
-            If a URI is used, protocol-specific parameters apply, given by
-            configuration parameter `slice_storage_options`.
+        slices: An iterable that yields slice items.
         config: Processor configuration.
             May be a file path or URI, a `dict`, `None`, or a sequence of
             the aforementioned. If a sequence is used, subsequent

zappend/slice/source.py

@@ -19,8 +19,8 @@ class SliceSource(ABC):
     A slice source is a closable source for a slice dataset.
 
     A slice source is intended to be implemented by users. An implementation
-    must provide the methods [get_dataset()][zappend.slice.abc.SliceSource.get_dataset]
-    and [close()][zappend.slice.abc.SliceSource.dispose].
+    must provide the methods [get_dataset()][zappend.api.SliceSource.get_dataset]
+    and [close()][zappend.api.SliceSource.close].
 
     If your slice source class requires the processing context,
     your class constructor may define a `ctx: Context` as 1st positional
@@ -63,7 +63,9 @@ def close(self):
             self.dispose()
 
     def dispose(self):
-        """Deprecated since version 0.6.0, override [close()][close] instead."""
+        """Deprecated since version 0.6.0, override
+        [close()][zappend.api.SliceSource.close] instead.
+        """
 
 
 SliceItem = str | FileObj | xr.Dataset | ContextManager[xr.Dataset] | SliceSource