ci: add local pre-commit hook to write datasets.yaml

.pre-commit-config.yaml

@@ -149,3 +149,12 @@ repos:
             '--disable=protected-access',
             '--rcfile=pylintrc',
           ]
+-   repo: local
+    hooks:
+      - id: write-datasets-yaml
+        name: write-datasets-yaml
+        entry: python src/pymovements/_scripts/write_datasets_yaml.py
+        language: python
+        verbose: true
+        additional_dependencies:
+        - pyyaml

src/pymovements/_scripts/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2025 The pymovements Project Authors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.

src/pymovements/_scripts/write_datasets_yaml.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2025 The pymovements Project Authors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Write datasets.yaml for DatasetLibrary."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+
+def main(
+        datasets_dirpath: str | Path = './src/pymovements/datasets',
+        datasets_yaml_filename: str = 'datasets.yaml',
+) -> int:
+    """Write datasets yaml file for DatasetLibrary.
+
+    Parameters
+    ----------
+    datasets_dirpath: str | Path
+        The path to the directory containing dataset definition yaml files.
+        (default: './src/pymovements/datasets')
+    datasets_yaml_filename: str
+        The filename of the datasets yaml file. (default: 'datasets.yaml')
+
+    Returns
+    -------
+    int
+        ``0`` if no changes needed, ``1`` otherwise.
+    """
+    datasets_dirpath = Path(datasets_dirpath)
+
+    dataset_filename_stems = sorted(
+        [
+            filepath.stem for filepath in datasets_dirpath.glob('*.yaml')
+            if filepath.name != datasets_yaml_filename  # Ignore datasets.yaml file.
+        ],
+    )
+
+    try:
+        with open(datasets_dirpath / datasets_yaml_filename, encoding='utf-8') as f:
+            dataset_yaml_content = yaml.safe_load(f)
+    except FileNotFoundError:
+        dataset_yaml_content = None
+
+    # File content matches. Exit successfully.
+    if dataset_filename_stems == dataset_yaml_content:
+        return 0
+
+    # We have some updates in the datasets directory. Update the datasets yaml file.
+    with open(datasets_dirpath / datasets_yaml_filename, 'w', encoding='utf-8') as f:
+        yaml.dump(dataset_filename_stems, f)
+
+    return 1
+
+
+if __name__ == '__main__':  # pragma: no cover
+    raise SystemExit(main())

tests/unit/_scripts/write_datasets_yaml_test.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2025 The pymovements Project Authors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Test write_datasets_yaml script."""
+from pathlib import Path
+
+import pytest
+import yaml
+
+from pymovements._scripts import write_datasets_yaml
+
+
+@pytest.fixture(name='make_datasets_directory')
+def make_datasets_directory_fixture(tmp_path):
+    def _make_datasets_directory(param: str, make_yaml: bool) -> Path:
+        datasets = []
+        if param in {'single', 'two'}:
+            filepath = tmp_path / 'first.yaml'
+            filepath.touch()
+            datasets.append('first')
+        if param == 'two':
+            filepath = tmp_path / 'second.yaml'
+            filepath.touch()
+            datasets.append('second')
+        if make_yaml:
+            with open(tmp_path / 'datasets.yaml', 'w', encoding='utf-8') as f:
+                yaml.dump(datasets, f)
+        return tmp_path
+
+    yield _make_datasets_directory
+
+
+@pytest.mark.parametrize(
+    ('fixture_args', 'expected_return', 'expected_yaml'),
+    [
+        pytest.param(
+            ['empty', False],
+            1,
+            [],
+            id='empty_new',
+        ),
+
+        pytest.param(
+            ['empty', True],
+            0,
+            [],
+            id='empty_exist',
+        ),
+
+        pytest.param(
+            ['single', False],
+            1,
+            ['first'],
+            id='single_new',
+        ),
+
+        pytest.param(
+            ['single', True],
+            0,
+            ['first'],
+            id='single_exist',
+        ),
+
+        pytest.param(
+            ['two', False],
+            1,
+            ['first', 'second'],
+            id='two_new',
+        ),
+
+        pytest.param(
+            ['two', True],
+            0,
+            ['first', 'second'],
+            id='two_exist',
+        ),
+    ],
+)
+def test_write_datasets_yaml(
+        fixture_args, expected_return, expected_yaml, make_datasets_directory,
+):
+    datasets_dirpath = make_datasets_directory(*fixture_args)
+    datasets_yaml_filename = 'datasets.yaml'
+
+    return_value = write_datasets_yaml.main(
+        datasets_dirpath=datasets_dirpath,
+        datasets_yaml_filename=datasets_yaml_filename,
+    )
+
+    with open(datasets_dirpath / datasets_yaml_filename, encoding='utf-8') as f:
+        yaml_content = yaml.safe_load(f)
+
+    assert return_value == expected_return
+    assert yaml_content == expected_yaml