Merge pull request #50 from bcdev/forman-opening_time

Check access latency

Author: forman

CHANGES.md

@@ -4,6 +4,9 @@
 
 ### Adjustments and Enhancements
 
+- Added a new core rule `access-latency` that can be used to check the
+  time it takes to open datasets.
+
 - Added HTML styling for both CLI output (`--format html`) and rendering
   of `Result` objects in Jupyter notebooks.
 

docs/rule-ref.md

@@ -5,6 +5,12 @@ New rules will be added by upcoming XRLint releases.
 
 ## Core Rules
 
+### :material-bug: `access-latency`
+
+Ensure that the time it takes to open a dataset from its source does a exceed a given `threshold` in seconds. The default threshold is `2.5`.
+
+Contained in:  `all`-:material-lightning-bolt: `recommended`-:material-alert:
+
 ### :material-lightbulb: `content-desc`
 
 A dataset should provide information about where the data came from and what has been done to it. This information is mainly for the benefit of human readers. The rule accepts the following configuration parameters:

docs/todo.md

@@ -5,8 +5,6 @@
 - support zarr >= 3 which we do not only because test 
   `tests/plugins/xcube/processors/test_mldataset.py` fails
   (see code TODO)
-- validate `RuleConfig.args/kwargs` against `RuleMeta.schema`
-  (see code TODO)
 - enhance docs
   - complete configuration page
   - provide guide page
@@ -21,11 +19,11 @@
 - add `core` rule checks recommended use of fill value
 - add `xcube` rule that helps to identify chunking issues 
 - apply rule op args/kwargs validation schema 
-- measure time it takes to open a dataset and pass time into rule context 
-  so we can write a configurable rule that checks the opening time
 - allow outputting suggestions, if any, that are emitted by some rules
   - add CLI option
   - expand/collapse messages with suggestions in Jupyter notebooks
+- validate `RuleConfig.args/kwargs` against `RuleMeta.schema`
+  (see code TODO)
 
 ## Nice to have
 

tests/_linter/test_rulectx.py

@@ -13,15 +13,18 @@ class RuleContextImplTest(TestCase):
     def test_defaults(self):
         config_obj = ConfigObject()
         dataset = xr.Dataset()
-        context = RuleContextImpl(config_obj, dataset, "./ds.zarr", None)
+        context = RuleContextImpl(config_obj, dataset, "./ds.zarr", None, None)
         self.assertIs(config_obj, context.config)
         self.assertIs(dataset, context.dataset)
         self.assertEqual({}, context.settings)
         self.assertEqual("./ds.zarr", context.file_path)
         self.assertEqual(None, context.file_index)
+        self.assertEqual(None, context.access_latency)
 
     def test_report(self):
-        context = RuleContextImpl(ConfigObject(), xr.Dataset(), "./ds.zarr", None)
+        context = RuleContextImpl(
+            ConfigObject(), xr.Dataset(), "./ds.zarr", None, 1.2345
+        )
         with context.use_state(rule_id="no-xxx"):
             context.report(
                 "What the heck do you mean?",

tests/plugins/core/rules/test_access_latency.py

@@ -0,0 +1,75 @@
+from unittest import TestCase
+
+import pytest
+import xarray as xr
+
+# noinspection PyProtectedMember
+from xrlint._linter.rulectx import RuleContextImpl
+from xrlint.config import ConfigObject
+from xrlint.node import DatasetNode
+from xrlint.plugins.core.rules.access_latency import AccessLatency
+from xrlint.result import Message
+from xrlint.rule import RuleExit
+
+valid_dataset_0 = xr.Dataset()
+
+invalid_dataset_0 = xr.Dataset()
+
+
+class OpeningTimeTest(TestCase):
+    @classmethod
+    def invoke_op(
+        cls, dataset: xr.Dataset, access_latency: float, threshold: float | None = None
+    ):
+        ctx = RuleContextImpl(
+            config=ConfigObject(),
+            dataset=dataset,
+            file_path="test.zarr",
+            file_index=None,
+            access_latency=access_latency,
+        )
+        node = DatasetNode(
+            path="dataset",
+            parent=None,
+            dataset=ctx.dataset,
+        )
+        rule_op = (
+            AccessLatency(threshold=threshold)
+            if threshold is not None
+            else AccessLatency()
+        )
+        with pytest.raises(RuleExit):
+            rule_op.validate_dataset(ctx, node)
+        return ctx
+
+    def test_valid(self):
+        ctx = self.invoke_op(xr.Dataset(), 1.0, threshold=None)
+        self.assertEqual([], ctx.messages)
+
+        ctx = self.invoke_op(xr.Dataset(), 1.0, threshold=1.0)
+        self.assertEqual([], ctx.messages)
+
+    def test_invalid(self):
+        ctx = self.invoke_op(xr.Dataset(), 3.16, threshold=None)
+        self.assertEqual(
+            [
+                Message(
+                    message="Access latency exceeds threshold: 3.2 > 2.5 seconds.",
+                    node_path="dataset",
+                    severity=2,
+                )
+            ],
+            ctx.messages,
+        )
+
+        ctx = self.invoke_op(xr.Dataset(), 0.2032, threshold=0.1)
+        self.assertEqual(
+            [
+                Message(
+                    message="Access latency exceeds threshold: 0.2 > 0.1 seconds.",
+                    node_path="dataset",
+                    severity=2,
+                )
+            ],
+            ctx.messages,
+        )

tests/plugins/core/test_plugin.py

@@ -8,15 +8,16 @@ def test_rules_complete(self):
         plugin = export_plugin()
         self.assertEqual(
             {
+                "access-latency",
                 "content-desc",
                 "conventions",
                 "coords-for-dims",
                 "grid-mappings",
                 "lat-coordinate",
                 "lon-coordinate",
                 "no-empty-attrs",
-                "time-coordinate",
                 "no-empty-chunks",
+                "time-coordinate",
                 "var-desc",
                 "var-flags",
                 "var-units",

xrlint/_linter/rulectx.py

@@ -17,6 +17,7 @@ def __init__(
         dataset: xr.Dataset,
         file_path: str,
         file_index: int | None,
+        access_latency: float | None,
     ):
         assert config is not None
         assert dataset is not None
@@ -26,6 +27,7 @@ def __init__(
         self._dataset = dataset
         self._file_path = file_path
         self._file_index = file_index
+        self._access_latency = access_latency
         self.messages: list[Message] = []
         self.rule_id: str | None = None
         self.severity: Literal[1, 2] = SEVERITY_ERROR
@@ -51,6 +53,10 @@ def file_path(self) -> str:
     def file_index(self) -> int | None:
         return self._file_index
 
+    @property
+    def access_latency(self) -> float | None:
+        return self._access_latency
+
     def report(
         self,
         message: str,

xrlint/_linter/validate.py

@@ -1,3 +1,4 @@
+import time
 from typing import Any
 
 import xarray as xr
@@ -15,7 +16,7 @@ def validate_dataset(config_obj: ConfigObject, dataset: Any, file_path: str):
     assert dataset is not None
     assert isinstance(file_path, str)
     if isinstance(dataset, xr.Dataset):
-        messages = _validate_dataset(config_obj, dataset, file_path, None)
+        messages = _validate_dataset(config_obj, dataset, file_path, None, None)
     else:
         messages = _open_and_validate_dataset(config_obj, dataset, file_path)
     return Result.new(config_object=config_obj, messages=messages, file_path=file_path)
@@ -26,12 +27,15 @@ def _validate_dataset(
     dataset: xr.Dataset,
     file_path: str,
     file_index: int | None,
+    access_latency: float | None,
 ) -> list[Message]:
     assert isinstance(config_obj, ConfigObject)
     assert isinstance(dataset, xr.Dataset)
     assert isinstance(file_path, str)
 
-    context = RuleContextImpl(config_obj, dataset, file_path, file_index)
+    context = RuleContextImpl(
+        config_obj, dataset, file_path, file_index, access_latency
+    )
     for rule_id, rule_config in config_obj.rules.items():
         with context.use_state(rule_id=rule_id):
             apply_rule(context, rule_id, rule_config)
@@ -48,24 +52,30 @@ def _open_and_validate_dataset(
     opener_options = config_obj.opener_options or {}
     if config_obj.processor is not None:
         processor_op = config_obj.get_processor_op(config_obj.processor)
+        t0 = time.time()
         try:
             ds_path_list = processor_op.preprocess(file_path, opener_options)
         except (OSError, ValueError, TypeError) as e:
             return [new_fatal_message(str(e))]
+        access_latency = time.time() - t0
         return processor_op.postprocess(
             [
-                _validate_dataset(config_obj, ds, path, i)
+                _validate_dataset(config_obj, ds, path, i, access_latency)
                 for i, (ds, path) in enumerate(ds_path_list)
             ],
             file_path,
         )
     else:
+        t0 = time.time()
         try:
             dataset = _open_dataset(ds_source, opener_options, file_path)
         except (OSError, ValueError, TypeError) as e:
             return [new_fatal_message(str(e))]
+        access_latency = time.time() - t0
         with dataset:
-            return _validate_dataset(config_obj, dataset, file_path, None)
+            return _validate_dataset(
+                config_obj, dataset, file_path, None, access_latency
+            )
 
 
 def _open_dataset(

xrlint/plugins/core/__init__.py

@@ -12,6 +12,7 @@ def export_plugin() -> Plugin:
         {
             "name": "recommended",
             "rules": {
+                "access-latency": "warn",
                 "content-desc": "warn",
                 "conventions": "warn",
                 "coords-for-dims": "error",

xrlint/plugins/core/plugin.py

@@ -1,4 +1,4 @@
-from xrlint.constants import CORE_PLUGIN_NAME, CORE_DOCS_URL
+from xrlint.constants import CORE_DOCS_URL, CORE_PLUGIN_NAME
 from xrlint.plugin import new_plugin
 from xrlint.version import version