permit_computed_attrs -> permit_eval;

new attrs_update_mode "ignore";
updated guide.

Author: forman

docs/config.md

@@ -146,28 +146,31 @@ Variable metadata.
 ## `attrs`
 
 Type _object_.
-Arbitrary dataset attributes. If `permit_computed_attrs` is set to `true`, string values may include Python expressions enclosed in `{{` and `}}` to dynamically compute attribute values; in the expression, the current dataset  is named `ds`. Refer to the user guide for more information.
+Arbitrary dataset attributes. If `permit_eval` is set to `true`, string values may include Python expressions enclosed in `{{` and `}}` to dynamically compute attribute values; in the expression, the current dataset  is named `ds`. Refer to the user guide for more information.
 
 ## `attrs_update_mode`
 
 The mode used update target attributes from slice attributes. Independently of this setting, extra attributes configured by the `attrs` setting will finally be used to update the resulting target attributes.
 Must be one of the following:
 
-  * Keep attributes from first slice dataset.
+  * Use attributes from first slice dataset and keep them.
     Its value is `"keep"`.
 
-  * Replace attributes from last slice dataset.
+  * Replace existing attributes by attributes of last slice dataset.
     Its value is `"replace"`.
 
-  * Update attributes from last slice dataset.
+  * Update existing attributes by attributes of last slice dataset.
     Its value is `"update"`.
 
+  * Ignore attributes from slice datasets.
+    Its value is `"ignore"`.
+
 Defaults to `"keep"`.
 
-## `permit_computed_attrs`
+## `permit_eval`
 
 Type _boolean_.
-Allow for dynamically computed values in dataset attributes `attrs` using the syntax `{{ expression }}`.  Executing arbitrary Python expressions is a security risk, therefore this must be explicitly enabled.
+Allow for dynamically computed values in dataset attributes `attrs` using the syntax `{{ expression }}`.  Executing arbitrary Python expressions is a security risk, therefore this must be explicitly enabled. Refer to the user guide for more information.
 Defaults to `false`.
 
 ## `target_dir`

docs/guide.md

@@ -156,14 +156,83 @@ Often, it is easier to specify which variables should be excluded:
 ```
 ### Attributes
 
-_TODO: Write section_
+The target dataset should exploit information about itself using global 
+metadata attributes.
+There are three choices to update the global attributes of the target 
+dataset from slices. The configuration setting `attrs_update_mode` 
+controls how this is done:
 
-Configuration settings:
+* `"keep"` - use attributes from first slice dataset and keep them (default);
+* `"replace"` - replace existing attributes by attributes of last slice dataset;
+* `"update"` - update existing attributes by attributes of last slice dataset;
+* `"ignore"` - ignore attributes from slice datasets.
 
-* `attrs`
-* `permit_dyn_attrs`
-* `attrs_update_mode`
+Extra attributes can be added using the optional configuration setting `attrs`:
 
+```json
+{
+    "attrs_update_mode": "keep",
+    "attrs": {
+        "Conventions": "CF-1.10",
+        "title": "SMOS Level 2C Soil Moisture 2-Days Composite"
+    }
+}
+```
+
+Independently of the `attrs_update_mode` setting, extra attributes configured 
+by the `attrs` setting will always be used to update the resulting target 
+attributes. 
+
+Attribute values in the `attrs` setting may also be computed dynamically using 
+the syntax `{{ expression }}`, where `expression` is an arbitrary Python 
+expression. For this to work, the setting `permit_eval` must be explicitly 
+set for security reasons:
+
+```json
+{
+    "permit_eval": true,
+    "attrs_update_mode": "keep",
+    "attrs": {
+        "time_coverage_start": "{{ ds.time[0] }}", 
+        "time_coverage_end": "{{ ds.time[-1] }}"
+    }
+}
+```
+
+Currently, the only variable accessible from expressions is `ds` which is 
+a reference to the current state of the target dataset after the last slice 
+append. It is of type 
+[xarray.Dataset](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html).
+
+!!! danger "Evil eval()"
+    The expressions in `{{ expression }}` are evaluated using the Python 
+    [eval() function](https://docs.python.org/3/library/functions.html#eval).
+    This can pose a threat to your application and environment. 
+    Although `zappend` does not allow you to directly access Python built-in 
+    functions via expressions, it should be used judiciously and with extreme 
+    caution if used as part of a web service where configuration is injected 
+    from the outside of your network.
+
+The following utility functions can be used as well and are handy if you need 
+to store the upper and lower bounds of coordinates as attribute values:
+
+* `lower_bound(array, ref: "lower"|"upper"|"center" = "lower")`:
+  Return the lower bound of a one-dimensional (coordinate) array `array`.
+* `upper_bound(array, ref: "lower"|"upper"|"center" = "lower")`:
+  Return the upper bound of a one-dimensional (coordinate) array `array`.
+ 
+The `ref` value specifies the reference within an array element that is used 
+as a basis for the boundary computation. E.g., if coordinate labels refer to 
+array element centers, pass `ref="center"`.
+    
+```json
+{
+    "attrs": {
+        "time_coverage_start": "{{ lower_bound(ds.time, 'center') }}", 
+        "time_coverage_end": "{{ upper_bound(ds.time, 'center') }}"
+    }
+}
+```
 
 ## Variable Metadata 
 

tests/config/test_schema.py

@@ -24,7 +24,7 @@ def test_get_config_schema(self):
                 "fixed_dims",
                 "included_variables",
                 "logging",
-                "permit_computed_attrs",
+                "permit_eval",
                 "persist_mem_slices",
                 "profiling",
                 "slice_engine",

tests/test_api.py

@@ -291,7 +291,7 @@ def test_dynamic_attrs_with_one_slice(self):
         zappend(
             slices,
             target_dir=target_dir,
-            permit_computed_attrs=True,
+            permit_eval=True,
             attrs={
                 "title": "HROC Ocean Colour Monthly Composite",
                 "time_coverage_start": "{{ ds.time[0] }}",
@@ -315,7 +315,7 @@ def test_dynamic_attrs_with_some_slices(self):
         zappend(
             slices,
             target_dir=target_dir,
-            permit_computed_attrs=True,
+            permit_eval=True,
             attrs={
                 "title": "HROC Ocean Colour Monthly Composite",
                 "time_coverage_start": "{{ ds.time[0] }}",

tests/test_context.py

@@ -62,18 +62,18 @@ def test_attrs(self):
         ctx = Context({"target_dir": "memory://target.zarr"})
         self.assertEqual({}, ctx.attrs)
         self.assertEqual("keep", ctx.attrs_update_mode)
-        self.assertEqual(False, ctx.computed_attrs_permitted)
+        self.assertEqual(False, ctx.permit_eval)
         ctx = Context(
             {
                 "target_dir": "memory://target.zarr",
                 "attrs": {"title": "OCC 2024"},
                 "attrs_update_mode": "update",
-                "permit_computed_attrs": True,
+                "permit_eval": True,
             }
         )
         self.assertEqual({"title": "OCC 2024"}, ctx.attrs)
         self.assertEqual("update", ctx.attrs_update_mode)
-        self.assertEqual(True, ctx.computed_attrs_permitted)
+        self.assertEqual(True, ctx.permit_eval)
 
     def test_slice_polling(self):
         ctx = Context({"target_dir": "memory://target.zarr"})

tests/test_tailoring.py

@@ -232,3 +232,14 @@ def test_it_updates_attrs_according_to_update_mode(self):
             },
             tailored_ds.attrs,
         )
+
+        tailored_ds = tailor_slice_dataset(
+            slice_ds, target_md, "time", "ignore", {"a": 12, "b": True}
+        )
+        self.assertEqual(
+            {
+                "a": 12,
+                "b": True,
+            },
+            tailored_ds.attrs,
+        )

zappend/config/schema.py

@@ -524,7 +524,7 @@
         attrs={
             "description": (
                 "Arbitrary dataset attributes."
-                " If `permit_computed_attrs` is set to `true`,"
+                " If `permit_eval` is set to `true`,"
                 " string values may include Python expressions"
                 " enclosed in `{{` and `}}` to dynamically compute"
                 " attribute values; in the expression, the current dataset "
@@ -543,26 +543,39 @@
             ),
             "oneOf": [
                 {
-                    "description": "Keep attributes from first slice dataset.",
+                    "description": (
+                        "Use attributes from first slice dataset and keep them."
+                    ),
                     "const": "keep",
                 },
                 {
-                    "description": "Replace attributes from last slice dataset.",
+                    "description": (
+                        "Replace existing attributes by attributes"
+                        " of last slice dataset."
+                    ),
                     "const": "replace",
                 },
                 {
-                    "description": "Update attributes from last slice dataset.",
+                    "description": (
+                        "Update existing attributes by attributes"
+                        " of last slice dataset."
+                    ),
                     "const": "update",
                 },
+                {
+                    "description": "Ignore attributes from slice datasets.",
+                    "const": "ignore",
+                },
             ],
             "default": DEFAULT_ATTRS_UPDATE_MODE,
         },
-        permit_computed_attrs={
+        permit_eval={
             "description": (
                 "Allow for dynamically computed values in dataset attributes"
                 " `attrs` using the syntax `{{ expression }}`. "
                 " Executing arbitrary Python expressions is a security"
                 " risk, therefore this must be explicitly enabled."
+                " Refer to the user guide for more information."
             ),
             "type": "boolean",
             "default": False,

zappend/context.py

@@ -119,13 +119,13 @@ def last_append_label(self) -> Any | None:
         return self._last_append_label
 
     @property
-    def computed_attrs_permitted(self) -> bool:
+    def permit_eval(self) -> bool:
         """Check if dynamically computed values in dataset attributes `attrs`
         using the syntax `{{ expression }}` is permitted. Executing arbitrary
         Python expressions is a security risk, therefore this must be explicitly
         enabled.
         """
-        return bool(self._config.get("permit_computed_attrs"))
+        return bool(self._config.get("permit_eval"))
 
     @property
     def target_metadata(self) -> DatasetMetadata | None:

zappend/processor.py

@@ -182,7 +182,7 @@ def post_create_target(ctx: Context, target_ds: xr.Dataset):
         target_ds: The target dataset.
     """
     target_attrs = target_ds.attrs
-    if ctx.computed_attrs_permitted and has_dyn_config_attrs(target_attrs):
+    if ctx.permit_eval and has_dyn_config_attrs(target_attrs):
         target_store = ctx.target_dir.fs.get_mapper(root=ctx.target_dir.path)
         resolve_target_attrs(target_store, target_ds, target_attrs)
 
@@ -197,7 +197,7 @@ def post_update_target(ctx: Context, target_store: RollbackStore, slice_ds: xr.D
         slice_ds: The current slice dataset that has already been appended.
     """
     target_attrs = slice_ds.attrs
-    if ctx.computed_attrs_permitted and has_dyn_config_attrs(target_attrs):
+    if ctx.permit_eval and has_dyn_config_attrs(target_attrs):
         with xr.open_zarr(target_store) as target_ds:
             resolve_target_attrs(target_store, target_ds, target_attrs)
 

zappend/tailoring.py

@@ -14,28 +14,33 @@
 from .metadata import DatasetMetadata
 
 
+# TODO: use ctx as only argument
 def tailor_target_dataset(
     dataset: xr.Dataset, target_metadata: DatasetMetadata
 ) -> xr.Dataset:
     dataset = _strip_dataset(dataset, target_metadata)
     dataset = _complete_dataset(dataset, target_metadata)
 
-    # Complement dataset attributes and set
-    # variable encoding and attributes
+    # TODO: use ctx.attrs_update_mode to set initial dataset attributes
+
+    # Set initial dataset attributes
     dataset.attrs = target_metadata.attrs
+
+    # Set variable encoding and attributes
     for var_name, var_metadata in target_metadata.variables.items():
         variable = dataset.variables[var_name]
         variable.encoding = var_metadata.encoding.to_dict()
         variable.attrs = var_metadata.attrs
     return dataset
 
 
+# TODO: use ctx and slice_ds as only arguments
 def tailor_slice_dataset(
     slice_ds: xr.Dataset,
     target_metadata: DatasetMetadata,
     append_dim: str = DEFAULT_APPEND_DIM,
     attrs_update_mode: (
-        Literal["keep"] | Literal["replace"] | Literal["update"]
+        Literal["keep"] | Literal["replace"] | Literal["update"] | Literal["ignore"]
     ) = DEFAULT_ATTRS_UPDATE_MODE,
     attrs: dict[str, Any] | None = None,
 ) -> xr.Dataset:
@@ -62,6 +67,9 @@ def tailor_slice_dataset(
     elif attrs_update_mode == "update":
         # Update from last slice dataset
         slice_ds.attrs = target_metadata.attrs | slice_ds.attrs
+    elif attrs_update_mode == "ignore":
+        # Ignore attributes from slice dataset
+        slice_ds.attrs = {}
     if attrs:
         # Always update by configured attributes
         slice_ds.attrs.update(attrs)