Merge branch 'main' into oras5

Author: valeriupredoi

.github/workflows/build-and-deploy-on-pypi.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false

.github/workflows/citation_file_validator.yml

@@ -19,7 +19,7 @@ jobs:
     if: github.repository == 'ESMValGroup/ESMValCore' # avoid GAs in forks
     steps:
       - name: Check out a copy of the repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
       - name: Check whether the citation metadata from CITATION.cff is valid

.github/workflows/run-tests-monitor.yml

@@ -31,7 +31,7 @@ jobs:
           - test-py314
     name: ${{ matrix.os }} ${{ matrix.environment }}
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false

.github/workflows/run-tests.yml

@@ -32,7 +32,7 @@ jobs:
           - test-r
     name: ${{ matrix.os }} ${{ matrix.environment }}
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false

.github/workflows/update-lockfiles.yml

@@ -14,7 +14,7 @@ jobs:
   pixi-update:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false

.zenodo.json

@@ -224,6 +224,11 @@
       "affiliation": "SMHI, Sweden",
       "name": "Lenhardt, Julien",
       "orcid": "https://orcid.org/0000-0002-9949-3989"
+    },
+    {
+      "affiliation": "Climate Resource, Australia",
+      "name": "Lewis, Jared",
+      "orcid": "https://orcid.org/0000-0002-8155-8924"
     }
   ],
   "description": "ESMValCore: A community tool for pre-processing data from Earth system models in CMIP and running analysis scripts.",

CITATION.cff

@@ -228,6 +228,11 @@ authors:
     family-names: Lenhardt
     given-names: Julien
     orcid: "https://orcid.org/0000-0002-9949-3989"
+  -
+    affiliation: "Climate Resource, Australia"
+    family-names: Lewis
+    given-names: Jared
+    orcid: "https://orcid.org/0000-0002-8155-8924"
 
 cff-version: 1.2.0
 date-released: 2026-03-10

esmvalcore/_main.py

@@ -607,7 +607,7 @@ def version(self):
         for project, version in self._extra_packages.items():
             print(f"{project}: {version}")  # noqa: T201
 
-    def run(self, recipe, **kwargs):
+    def run(self, recipe, session_name=None, **kwargs):
         """Execute an ESMValTool recipe.
 
         `esmvaltool run` executes the given recipe. To see a list of available
@@ -617,6 +617,15 @@ def run(self, recipe, **kwargs):
         A list of possible flags is given here:
         https://docs.esmvaltool.org/projects/ESMValCore/en/latest/quickstart/configure.html#configuration-options
 
+        Parameters
+        ----------
+        recipe:
+            Path to the recipe to run.
+        session_name:
+            Name of the session output subdirectory (relative to the configured ``output_dir``).
+            When given, this value is used instead of the default ``<recipe.stem>_<timestamp>``.
+
+            If the given name already exists, a suffix is added to the session name to avoid overwriting existing data.
         """
         from .config import CFG
         from .exceptions import InvalidConfigParameter
@@ -651,6 +660,8 @@ def run(self, recipe, **kwargs):
 
         CFG["resume_from"] = parse_resume(CFG["resume_from"], recipe)
         session = CFG.start_session(recipe.stem)
+        if session_name is not None:
+            session.session_name = str(session_name)
 
         self._run(recipe, session, cli_config_dir)
 

tests/unit/main/test_esmvaltool.py

@@ -96,6 +96,44 @@ def test_run_command_line_config(mocker, cfg, argument, value, tmp_path):
     assert session[argument] == value
 
 
+def test_run_session_name(mocker, cfg, tmp_path):
+    """Check that `session_name` overrides the auto-generated name."""
+    mocker.patch.object(esmvalcore.config, "CFG", cfg)
+    session = cfg.start_session.return_value
+
+    program = ESMValTool()
+    recipe_file = "/path/to/recipe_test.yml"
+    config_dir = tmp_path / "config"
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    mocker.patch.object(program, "_get_recipe", return_value=Path(recipe_file))
+    mocker.patch.object(program, "_run")
+
+    program.run(recipe_file, session_name="result", config_dir=config_dir)
+
+    assert session.session_name == "result"
+    # Check that the session name is not passed to the cfg
+    for call in cfg.nested_update.call_args_list:
+        assert "session_name" not in call.args[0]
+
+
+def test_run_no_session_name(mocker, cfg, tmp_path):
+    """Check that the session name is left untouched by default."""
+    mocker.patch.object(esmvalcore.config, "CFG", cfg)
+
+    program = ESMValTool()
+    recipe_file = "/path/to/recipe_test.yml"
+    config_dir = tmp_path / "config"
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    mocker.patch.object(program, "_get_recipe", return_value=Path(recipe_file))
+    mocker.patch.object(program, "_run")
+
+    program.run(recipe_file, config_dir=config_dir)
+
+    assert "session_name" not in cfg.start_session.return_value.__dict__
+
+
 @pytest.mark.parametrize("search_data", ["quick", "complete"])
 def test_run(mocker, session, search_data):
     session["search_data"] = search_data