Modify Payu config parser to have a similar API to the other config parsers.

Author: micaeljtoliveira

src/access/parsers/payu_config_yaml.py

@@ -1,44 +1,53 @@
 # Copyright 2025 ACCESS-NRI and contributors. See the top-level COPYRIGHT file for details.
 # SPDX-License-Identifier: Apache-2.0
 
-"""Utilities to handle payu configuration files.
+"""Utilities to handle YAML-based configuration files.
 
-Configuration for payu experiments are stored using YAML. Documentation about these files can be found here:
-
-    https://payu.readthedocs.io/en/latest/config.html
-
-Round-trip parsing is supported by using the ruamel.yaml parser.
+The ruamel.yaml parser provides round-trip parsing of YAML files and has all capabilities we require. Here we simply
+provide wrappers around the ruamel.yaml classes so that the API is the same/similar to the other parsers.
 """
 
-from pathlib import Path
+from io import StringIO
+from typing import Any
+
 from ruamel.yaml import YAML, CommentedMap
 
 
-def read_payu_config_yaml(file_name: str) -> CommentedMap:
-    """Read a payu configuration file.
+class YAMLConfig(dict):
+    """Class to store a YAML configuration as a dict.
+
+    The YAML parsers generates an instance of CommentedMap, which in turn also behaves like a dictionary. Unfortunately
+    we cannot simply subclass CommentedMap. This is because the dump method of YAML calls the __str__ method of
+    CommentedMap, which leads to a infinite recursion when calling the __str__ method of this class. This means that,
+    instead, we need to keep a copy of the CommentedMap and sync it with the dict.
+    """
 
-    This function uses ruamel to parse the YAML file, so that we can do round-trip parsing.
+    def __init__(self, map: CommentedMap) -> None:
+        self.map = map
+        super().__init__(map)
 
-    Args:
-        file_name: Name of file to read.
+    def __str__(self) -> str:
+        output = StringIO("")
+        YAML().dump(self.map, output)
+        return output.getvalue()
 
-    Returns:
-        dict: Payu configuration.
-    """
-    fname = Path(file_name)
-    if not fname.is_file():
-        raise FileNotFoundError(f"File not found: {fname.as_posix()}")
+    def __setitem__(self, key: str, value: Any) -> None:
+        super().__setitem__(key, value)
+        self.map[key] = value
 
-    config = YAML().load(fname)
+    def __getitem__(self, key: str) -> Any:
+        return self.map[key]
 
-    return config
+    def __delitem__(self, key: str) -> None:
+        super().__delitem__(key)
+        del self.map[key]
 
 
-def write_payu_config_yaml(config: [dict | CommentedMap], file: Path):
-    """Write a Payu configuration to a file.
+class YAMLParser:
+    """Wrapper class to the ruamel.yaml parser."""
 
-    Args:
-        config (dict| CommentedMap): Payu configuration.
-        file(Path): File to write to.
-    """
-    YAML().dump(config, file)
+    def __init__(self) -> None:
+        self.parser = YAML()
+
+    def parse(self, stream: str) -> YAMLConfig:
+        return YAMLConfig(self.parser.load(stream))

tests/test_payu_config_yaml.py

@@ -2,14 +2,19 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import pytest
-from unittest.mock import mock_open, patch
-from pathlib import Path
 
-from access.parsers.payu_config_yaml import read_payu_config_yaml, write_payu_config_yaml
+from access.parsers.payu_config_yaml import YAMLParser
+
+
+@pytest.fixture(scope="module")
+def parser():
+    """Fixture instantiating the parser."""
+    return YAMLParser()
 
 
 @pytest.fixture()
 def simple_payu_config():
+    """Fixture returning a dictionary storing a payu config file."""
     return {
         "project": "x77",
         "ncpus": 48,
@@ -29,6 +34,7 @@ def simple_payu_config():
 
 @pytest.fixture()
 def simple_payu_config_file():
+    """Fixture returning the contents of a simple payu config file."""
     return """project: x77
 ncpus: 48
 jobfs: 10GB
@@ -45,7 +51,8 @@ def simple_payu_config_file():
 
 
 @pytest.fixture()
-def complex_payu_config_file():
+def payu_config_file():
+    """Fixture returning the contents of a more complex payu config file."""
     return """# PBS configuration
 
 # If submitting to a different project to your default, uncomment line below
@@ -75,6 +82,7 @@ def complex_payu_config_file():
 
 @pytest.fixture()
 def modified_payu_config_file():
+    """Fixture returning the contents the previous payu config file after introducing some modifications."""
     return """# PBS configuration
 
 # If submitting to a different project to your default, uncomment line below
@@ -93,7 +101,6 @@ def modified_payu_config_file():
 
 model: access-om3
 
-exe: /some/path/to/access-om3-MOM6-CICE6
 input:
 - /some/other/path/to/inputs/1deg/mom # MOM6 inputs
 - /some/path/to/inputs/1deg/cice      # CICE inputs
@@ -102,33 +109,19 @@ def modified_payu_config_file():
 """
 
 
-@patch("pathlib.Path.is_file", new=lambda file: True)
-def test_read_payu_config(simple_payu_config, simple_payu_config_file):
-    with patch("io.open", mock_open(read_data=simple_payu_config_file)) as m:
-        config = read_payu_config_yaml(file_name="simple_payu_config_file")
-
-        assert config == simple_payu_config
-
-
-def test_write_payu_config(simple_payu_config, simple_payu_config_file):
-    with patch("io.open", mock_open()) as m:
-        write_payu_config_yaml(simple_payu_config, Path("config_file"))
-
-        assert simple_payu_config_file == "".join(call.args[0] for call in m().write.mock_calls)
-
+def test_read_payu_config(parser, simple_payu_config, simple_payu_config_file):
+    """Test parsing of a simple file."""
+    config = parser.parse(simple_payu_config_file)
 
-@patch("pathlib.Path.is_file", new=lambda file: True)
-def test_round_trip_payu_config(complex_payu_config_file, modified_payu_config_file):
-    with patch("io.open", mock_open(read_data=complex_payu_config_file)) as m:
-        config = read_payu_config_yaml(file_name="complex_config_file")
+    assert config == simple_payu_config
 
-        config["ncpus"] = 64
-        config["input"][0] = "/some/other/path/to/inputs/1deg/mom"
-        write_payu_config_yaml(config, Path("some_other_config_file"))
 
-        assert modified_payu_config_file == "".join(call.args[0] for call in m().write.mock_calls)
+def test_round_trip_payu_config(parser, payu_config_file, modified_payu_config_file):
+    """Test round-trip parsing of a more complex file with mutation of the config."""
+    config = parser.parse(payu_config_file)
 
+    config["ncpus"] = 64
+    config["input"][0] = "/some/other/path/to/inputs/1deg/mom"
+    del config["exe"]
 
-def test_read_missing_payu_config():
-    with pytest.raises(FileNotFoundError):
-        read_payu_config_yaml(file_name="garbage")
+    assert modified_payu_config_file == str(config)