Merge pull request #48 from bcdev/use_google_docstrings

Ensure Google-style docstrings

Author: forman

zappend/api.py

@@ -50,13 +50,13 @@ def zappend(
 
     Args:
         slices: An iterable that yields slice objects. A slice object is
-            either a ``str``, ``xarray.Dataset``, ``SliceSource`` or a factory
-            function that returns a slice object. If ``str`` is used,
+            either a `str`, `xarray.Dataset`, `SliceSource` or a factory
+            function that returns a slice object. If `str` is used,
             it is interpreted as local dataset path or dataset URI.
             If a URI is used, protocol-specific parameters apply, given by
-            configuration parameter ``slice_storage_options``.
+            configuration parameter `slice_storage_options`.
         config: Processor configuration.
-            May be a file path or URI, a ``dict``, ``None``, or a sequence of
+            May be a file path or URI, a `dict`, `None`, or a sequence of
             the aforementioned. If a sequence is used, subsequent configurations
             are incremental to the previous ones.
         kwargs: Additional configuration parameters.

zappend/fsutil/transaction.py

@@ -28,47 +28,55 @@
 
 
 class Transaction:
-    """
-    A filesystem transaction.
+    """A filesystem transaction.
 
     Its main motivation is implementing transactional Zarr dataset
     modifications, because this does not exist for Zarr yet (2024-01), see
     https://github.com/zarr-developers/zarr-python/issues/247.
 
-    The ``Transaction`` class is used to observe changes to a given target
-    directory *target_dir*.
+    The `Transaction` class is used to observe changes to a given target
+    directory `target_dir`.
 
     Changes must be explicitly registered using a "rollback callback"
     function that is provided as the result of using the
-    transaction instance as a context manager:::
+    transaction instance as a context manager:
 
+    ```python
     with Transaction(target_dir, temp_dir) as rollback_cb:
         # emit rollback actions here
+    ```
 
     The following actions are supported:
 
-    * ``rollback_cb("delete_dir", path)`` if a directory has been created.
-    * ``rollback_cb("delete_file", path)`` if a file has been created.
-    * ``rollback_cb("replace_file", path, original_data)`` if a directory has
+    * `rollback_cb("delete_dir", path)` if a directory has been created.
+    * `rollback_cb("delete_file", path)` if a file has been created.
+    * `rollback_cb("replace_file", path, original_data)` if a directory has
         been changed.
 
-    Reported paths must be relative to *target_dir*. The empty path ``""``
-    refers to *target_dir* itself.
+    Reported paths must be relative to `target_dir`. The empty path `""`
+    refers to `target_dir` itself.
 
     When entering the context, a lock file will be created which prevents
-    other transactions to modify *target_dir*. The lock file will be placed
+    other transactions to modify `target_dir`. The lock file will be placed
     next to *target_dir* and its name is the filename of *target_dir* with a
-    ``.lock`` extension. The lock file will be removed on context exit.
-
-    :param target_dir: The target directory that is subject to this
-        transaction. All paths emitted to the rollback callback must be
-        relative to *target_dir*. The directory may or may not exist yet.
-    :param temp_dir: Temporary directory in which a unique subdirectory
-        will be created that will be used to collect
-        rollback data during the transaction. The directory must exist.
-    :param disable_rollback: Disable rollback entirely.
-        No rollback data will be written, however a lock file will still
-        be created for the duration of the transaction.
+    `.lock` extension. The lock file will be removed on context exit.
+
+    Args:
+        target_dir: The target directory that is subject to this
+            transaction. All paths emitted to the rollback callback must be
+            relative to *target_dir*. The directory may or may not exist yet.
+        temp_dir: Temporary directory in which a unique subdirectory
+            will be created that will be used to collect
+            rollback data during the transaction. The directory must exist.
+        disable_rollback: Disable rollback entirely.
+            No rollback data will be written, however a lock file will still
+            be created for the duration of the transaction.
+    Raises:
+        OSError: If the target is locked or the lock could not be removed.
+        TypeError: If the returned callback is not used appropriately.
+        ValueError: If instances of this class are not used as a context
+            manager, or if the returned callback is not used appropriately,
+            and in some other cases.
     """
 
     def __init__(
@@ -109,7 +117,7 @@ def __enter__(self):
 
         lock_file = self._lock_file
         if lock_file.exists():
-            raise IOError(f"Target is locked: {lock_file.uri}")
+            raise OSError(f"Target is locked: {lock_file.uri}")
         lock_file.write(self._rollback_dir.uri)
 
         if not self._disable_rollback:
@@ -209,5 +217,5 @@ def _add_rollback_action(
     def _assert_entered_ctx(self):
         if not self._entered_ctx:
             raise ValueError(
-                "Transaction instance" " must be used with the 'with' statement"
+                "Transaction instance must be used with the 'with' statement"
             )

zappend/metadata.py

@@ -79,7 +79,7 @@ def to_dict(self):
 class VariableMetadata:
     """Metadata for a dataset variable.
 
-    Arguments:
+    Args:
         dims: The names of the variable's dimensions.
         shape: The sizes of the variable's dimensions. This is a derived value,
             because the dimension size are given by the variable's dataset.
@@ -119,7 +119,7 @@ def __init__(
     ):
         """Dataset metadata including metadata for variables.
 
-        Arguments:
+        Args:
             sizes: A mapping from dimension name to dimension size.
             variables: A mapping from variable name to variable metadata.
             attrs: Arbitrary metadata attributes.
@@ -142,7 +142,7 @@ def assert_compatible_slice(
         """Assert a given slice dataset's metadata is compatible with this
         (target) dataset's metadata.
 
-        Arguments:
+        Args:
             slice_metadata: The slice dataset metadata.
             append_dim: The name of the append dimension.
 
@@ -191,7 +191,7 @@ def from_dataset(cls, dataset: xr.Dataset, config: dict[str, Any] | None = None)
         Encoding information found in dataset variables is normalized to valid
         Zarr encoding.
 
-        Arguments:
+        Args:
             dataset: A dataset
             config: Optional processor configuration
 

zappend/processor.py

@@ -27,7 +27,7 @@ class Processor:
 
     Args:
         config: Processor configuration.
-            May be a file path or URI, a ``dict``, ``None``, or a sequence of
+            May be a file path or URI, a `dict`, `None`, or a sequence of
             the aforementioned. If a sequence is used, subsequent configurations
             are incremental to the previous ones.
         kwargs: Additional configuration parameters.
@@ -44,7 +44,7 @@ def __init__(self, config: ConfigLike = None, **kwargs):
 
     def process_slices(self, slices: Iterable[SliceObj]):
         """Process the given *slices*.
-        Passes each slice in *slices* to the ``process_slice()`` method.
+        Passes each slice in *slices* to the `process_slice()` method.
 
         Args:
             slices: Slice objects.
@@ -57,11 +57,11 @@ def process_slice(self, slice_obj: SliceObj, slice_index: int = 0):
         """Process a single slice object *slice_obj*.
 
         A slice object is
-        either a ``str``, ``xarray.Dataset``, ``SliceSource`` or a factory
-        function that returns a slice object. If ``str`` is used,
+        either a `str`, `xarray.Dataset`, `SliceSource`` or a factory
+        function that returns a slice object. If `str` is used,
         it is interpreted as local dataset path or dataset URI.
         If a URI is used, protocol-specific parameters apply, given by
-        configuration parameter ``slice_storage_options``.
+        configuration parameter `slice_storage_options`.
 
         If there is no target yet, just config and slice:
 

zappend/profiler.py

@@ -18,7 +18,7 @@ def __init__(self, profiling_config: dict[str, Any] | str | bool | None):
         Intended to be used as context manager.
         For internal use only; this class does not belong to the API.
 
-        Arguments:
+        Args:
              profiling_config: The validated(!) "profiling" setting from
              the configuration.
         """