Refactored and renamed CliEngine into XRLint. Documented the class.

Author: forman

CHANGES.md

@@ -2,9 +2,10 @@
 
 ## Version 0.1.0 (in development)
 
-- Added CLI option `--print-config FILE`, see same option in ESLint
+- Added CLI option `--print-config PATH`, see same option in ESLint
 - XRLint CLI now outputs single results immediately to console,
   instead only after all results have been collected.
+- Refactored and renamed `CliEngine` into `XRLint`. Documented the class.
 
 
 ## Early development snapshots

docs/todo.md

@@ -13,10 +13,6 @@
 - project logo
 - if configuration for given FILE is empty,
   report an error, see TODO in CLI main tests
-- rename `xrlint.cli.CliEngine` into `xrlint.cli.XRLint`
-  (with similar API as the `ESLint` class) and export it 
-  from `xrlint.all`. Value of `FILES` should be passed to
-  `verify_datasets()` methods.
 - use `RuleMeta.docs_url` in formatters to create links
 - implement xarray backend for xcube 'levels' format
   so can validate them too

tests/cli/test_main.py

@@ -3,6 +3,7 @@
 import shutil
 from unittest import TestCase
 
+import click.testing
 from click.testing import CliRunner
 import xarray as xr
 
@@ -17,8 +18,6 @@
     dataset-title-attr: error
 """
 
-no_match_config_yaml = "[]"
-
 
 # noinspection PyTypeChecker
 class CliMainTest(TestCase):
@@ -55,23 +54,32 @@ def tearDownClass(cls):
         os.chdir(cls.last_cwd)
         shutil.rmtree(cls.temp_dir)
 
-    def test_no_files(self):
+    def xrlint(self, *args: tuple[str, ...]) -> click.testing.Result:
         runner = CliRunner()
-        result = runner.invoke(main)
-        self.assertIn("No dataset files provided.", result.output)
-        self.assertEqual(1, result.exit_code)
+        result = runner.invoke(main, args)
+        if not isinstance(result.exception, SystemExit):
+            self.assertIsNone(None, result.exception)
+        return result
 
-    def test_files_no_rules(self):
-        runner = CliRunner()
-        result = runner.invoke(main, self.files)
-        self.assertIn("Warning: no configuration file found.", result.output)
-        self.assertIn("No rules configured or applicable.", result.output)
+    def test_no_files_no_config(self):
+        result = self.xrlint()
+        self.assertEqual("", result.output)
+        self.assertEqual(0, result.exit_code)
+
+    def test_config_no_files(self):
+        with text_file(DEFAULT_CONFIG_FILE_YAML, self.ok_config_yaml):
+            result = self.xrlint()
+            self.assertEqual("", result.output)
+            self.assertEqual(0, result.exit_code)
+
+    def test_files_no_config(self):
+        result = self.xrlint(*self.files)
+        self.assertIn("Warning: no configuration file found.\n", result.output)
         self.assertEqual(1, result.exit_code)
 
     def test_files_one_rule(self):
         with text_file(DEFAULT_CONFIG_FILE_YAML, self.ok_config_yaml):
-            runner = CliRunner()
-            result = runner.invoke(main, ["--no-color"] + self.files)
+            result = self.xrlint("--no-color", *self.files)
             self.assertEqual(
                 "\n"
                 "dataset1.zarr - ok\n\n"
@@ -84,16 +92,14 @@ def test_files_one_rule(self):
             self.assertEqual(0, result.exit_code)
 
         with text_file(DEFAULT_CONFIG_FILE_YAML, self.fail_config_yaml):
-            runner = CliRunner()
-            result = runner.invoke(main, self.files)
+            result = self.xrlint(*self.files)
             self.assertIn("Missing metadata, attributes are empty.", result.output)
             self.assertIn("no-empty-attrs", result.output)
             self.assertEqual(1, result.exit_code)
 
     def test_dir_one_rule(self):
         with text_file(DEFAULT_CONFIG_FILE_YAML, self.ok_config_yaml):
-            runner = CliRunner()
-            result = runner.invoke(main, ["--no-color", "."])
+            result = self.xrlint("--no-color", ".")
             prefix = self.temp_dir.replace("\\", "/")
             self.assertIn(f"{prefix}/dataset1.zarr - ok\n\n", result.output)
             self.assertIn(f"{prefix}/dataset1.nc - ok\n\n", result.output)
@@ -103,16 +109,15 @@ def test_dir_one_rule(self):
             self.assertEqual(0, result.exit_code)
 
         with text_file(DEFAULT_CONFIG_FILE_YAML, self.fail_config_yaml):
-            runner = CliRunner()
-            result = runner.invoke(main, self.files)
+            result = self.xrlint(*self.files)
             self.assertIn("Missing metadata, attributes are empty.", result.output)
             self.assertIn("no-empty-attrs", result.output)
             self.assertEqual(1, result.exit_code)
 
     def test_color_no_color(self):
         with text_file(DEFAULT_CONFIG_FILE_YAML, self.ok_config_yaml):
-            runner = CliRunner()
-            result = runner.invoke(main, ["--no-color"] + self.files)
+            result = self.xrlint("--no-color", *self.files)
+            self.assertIsNone(result.exception)
             self.assertEqual(
                 "\n"
                 "dataset1.zarr - ok\n\n"
@@ -138,66 +143,68 @@ def test_color_no_color(self):
             self.assertEqual(0, result.exit_code)
 
     def test_files_with_rule_option(self):
-        runner = CliRunner()
-        result = runner.invoke(
-            main,
-            [
-                "--rule",
-                "no-empty-attrs: error",
-            ]
-            + self.files,
-        )
+        result = self.xrlint("--rule", "no-empty-attrs: error", *self.files)
         self.assertIn("Missing metadata, attributes are empty.", result.output)
         self.assertIn("no-empty-attrs", result.output)
         self.assertEqual(1, result.exit_code)
 
     def test_files_with_plugin_and_rule_options(self):
-        runner = CliRunner()
-        result = runner.invoke(
-            main,
-            [
-                "--plugin",
-                "xrlint.plugins.xcube",
-                "--rule",
-                "xcube/any-spatial-data-var: error",
-            ]
-            + self.files,
+        result = self.xrlint(
+            "--plugin",
+            "xrlint.plugins.xcube",
+            "--rule",
+            "xcube/any-spatial-data-var: error",
+            *self.files,
         )
         self.assertIn("No spatial data variables found.", result.output)
         self.assertIn("xcube/any-spatial-data-var", result.output)
         self.assertEqual(1, result.exit_code)
 
     def test_files_with_output_file(self):
         with text_file(DEFAULT_CONFIG_FILE_YAML, self.ok_config_yaml):
-            runner = CliRunner()
-            result = runner.invoke(main, ["-o", "memory://report.txt"] + self.files)
+            result = self.xrlint("-o", "memory://report.txt", *self.files)
             self.assertEqual("", result.output)
             self.assertEqual(0, result.exit_code)
 
     def test_files_but_config_file_missing(self):
-        runner = CliRunner()
-        result = runner.invoke(main, ["-c", "pippo.py"] + self.files)
+        result = self.xrlint("-c", "pippo.py", *self.files)
         self.assertIn("Error: file not found: pippo.py", result.output)
         self.assertEqual(1, result.exit_code)
 
     def test_files_with_format_option(self):
         with text_file(DEFAULT_CONFIG_FILE_YAML, self.ok_config_yaml):
-            runner = CliRunner()
-            result = runner.invoke(main, ["-f", "json"] + self.files)
+            result = self.xrlint("-f", "json", *self.files)
             self.assertIn('"results": [\n', result.output)
             self.assertEqual(0, result.exit_code)
 
     def test_file_does_not_match(self):
         with text_file(DEFAULT_CONFIG_FILE_YAML, no_match_config_yaml):
-            runner = CliRunner()
-            result = runner.invoke(main, ["test.zarr"])
+            result = self.xrlint("test.zarr")
             # TODO: make this assertion work
             # self.assertIn("No configuration matches this file.", result.output)
             self.assertEqual(1, result.exit_code)
 
+    def test_print_config_option(self):
+        with text_file(DEFAULT_CONFIG_FILE_YAML, self.ok_config_yaml):
+            result = self.xrlint("--print-config", "dataset2.zarr")
+            self.assertEqual(
+                (
+                    "{\n"
+                    '  "name": "<computed>",\n'
+                    '  "plugins": {\n'
+                    '    "__core__": "xrlint.plugins.core"\n'
+                    "  },\n"
+                    '  "rules": {\n'
+                    '    "dataset-title-attr": 2\n'
+                    "  }\n"
+                    "}\n"
+                ),
+                result.output,
+            )
+            self.assertEqual(0, result.exit_code)
+
     def test_files_with_invalid_format_option(self):
-        runner = CliRunner()
-        result = runner.invoke(main, ["-f", "foo"] + self.files)
+        result = self.xrlint("-f", "foo", *self.files)
         self.assertIn(
             "Error: unknown format 'foo'. The available formats are '", result.output
         )
@@ -208,8 +215,7 @@ def test_init(self):
         exists = os.path.exists(config_file)
         self.assertFalse(exists)
         try:
-            runner = CliRunner()
-            result = runner.invoke(main, ["--init"])
+            result = self.xrlint("--init")
             self.assertEqual(
                 f"Configuration template written to {config_file}\n", result.output
             )
@@ -225,8 +231,7 @@ def test_init_exists(self):
         exists = os.path.exists(config_file)
         self.assertFalse(exists)
         with text_file(config_file, ""):
-            runner = CliRunner()
-            result = runner.invoke(main, ["--init"])
+            result = self.xrlint("--init")
             self.assertEqual(
                 f"Error: file {config_file} already exists.\n", result.output
             )

tests/formatters/helpers.py

@@ -1,11 +1,31 @@
 from xrlint.config import Config
+from xrlint.formatter import FormatterContext
 from xrlint.plugin import Plugin
 from xrlint.plugin import PluginMeta
-from xrlint.result import Message
+from xrlint.result import Message, ResultStats
 from xrlint.result import Result
 from xrlint.rule import RuleOp
 
 
+class FormatterContextImpl(FormatterContext):
+
+    def __init__(self, max_warnings: int = -1):
+        self._max_warnings = max_warnings
+        self._result_stats = ResultStats()
+
+    @property
+    def max_warnings_exceeded(self) -> bool:
+        return self._result_stats.warning_count > self._max_warnings
+
+    @property
+    def result_stats(self) -> ResultStats:
+        return self._result_stats
+
+
+def get_context(max_warnings: int = -1) -> FormatterContext:
+    return FormatterContextImpl(max_warnings)
+
+
 def get_test_results():
 
     plugin = Plugin(meta=PluginMeta(name="test"))

tests/formatters/test_html.py

@@ -1,16 +1,15 @@
 from unittest import TestCase
 
-from xrlint.formatter import FormatterContext
 from xrlint.formatters.html import Html
-from .helpers import get_test_results
+from .helpers import get_test_results, get_context
 
 
 class HtmlTest(TestCase):
     def test_html(self):
         results = get_test_results()
         formatter = Html()
         text = formatter.format(
-            context=FormatterContext(),
+            context=get_context(),
             results=results,
         )
         self.assertIsInstance(text, str)
@@ -20,7 +19,7 @@ def test_html_with_meta(self):
         results = get_test_results()
         formatter = Html(with_meta=True)
         text = formatter.format(
-            context=FormatterContext(),
+            context=get_context(),
             results=results,
         )
         self.assertIsInstance(text, str)

tests/formatters/test_json.py

@@ -1,16 +1,15 @@
 from unittest import TestCase
 
-from xrlint.formatter import FormatterContext
 from xrlint.formatters.json import Json
-from .helpers import get_test_results
+from .helpers import get_test_results, get_context
 
 
 class JsonTest(TestCase):
     def test_json(self):
         results = get_test_results()
         formatter = Json()
         text = formatter.format(
-            context=FormatterContext(),
+            context=get_context(),
             results=results,
         )
         self.assertIn('"results": [', text)
@@ -19,7 +18,7 @@ def test_json_with_meta(self):
         results = get_test_results()
         formatter = Json(with_meta=True)
         text = formatter.format(
-            context=FormatterContext(),
+            context=get_context(),
             results=results,
         )
         self.assertIn('"results": [', text)

tests/formatters/test_markdown.py

@@ -2,9 +2,8 @@
 
 import pytest
 
-from xrlint.formatter import FormatterContext
 from xrlint.formatters.markdown import Markdown
-from .helpers import get_test_results
+from .helpers import get_test_results, get_context
 
 
 class MarkdownTest(TestCase):
@@ -13,6 +12,6 @@ def test_markdown(self):
         formatter = Markdown()
         with pytest.raises(NotImplementedError):
             formatter.format(
-                context=FormatterContext(),
+                context=get_context(),
                 results=get_test_results(),
             )

tests/formatters/test_simple.py

@@ -1,7 +1,7 @@
 from unittest import TestCase
 
+from tests.formatters.helpers import get_context
 from xrlint.config import Config
-from xrlint.formatter import FormatterContext
 from xrlint.formatters.simple import Simple
 from xrlint.result import Message
 from xrlint.result import Result
@@ -23,7 +23,7 @@ class SimpleTest(TestCase):
     def test_no_color(self):
         formatter = Simple(styled=False)
         text = formatter.format(
-            context=FormatterContext(),
+            context=get_context(),
             results=self.results,
         )
         self.assert_output_ok(text)
@@ -32,7 +32,7 @@ def test_no_color(self):
     def test_color(self):
         formatter = Simple(styled=True)
         text = formatter.format(
-            context=FormatterContext(),
+            context=get_context(),
             results=self.results,
         )
         self.assert_output_ok(text)