Merge pull request #19 from ubdbra001/issue_5/add_cli

feat: Add CLI

Author: effigies

.github/workflows/build-test-deploy.yml

@@ -36,6 +36,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          submodules: true
       - uses: hynek/build-and-inspect-python-package@v2
         with:
           # Use attestation only if the action is triggered inside the repo
@@ -65,6 +66,9 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
+
       - name: Set git name/email
         run: |
           git config --global user.email "[email protected]"

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "tests/data/bids-examples"]
+	path = tests/data/bids-examples
+	url = https://github.com/bids-standard/bids-examples

pyproject.toml

@@ -32,10 +32,17 @@ test = [
   "coverage[toml] >=7.2",
   "datalad >=1.1",
 ]
+cli = [
+  "typer >=0.15",
+]
 
 [project.urls]
 Homepage = "https://github.com/bids-standard/python-validator"
 
+[project.scripts]
+bids-validator = "bids_validator.__main__:app"
+bids-validator-python = "bids_validator.__main__:app"
+
 [tool.setuptools]
 package-dir = {"" = "src"}
 
@@ -55,12 +62,14 @@ tag_prefix = ""
 parentdir_prefix = ""
 
 [tool.pytest.ini_options]
+norecursedirs = ["data"]
 doctest_optionflags = ["NORMALIZE_WHITESPACE", "IGNORE_EXCEPTION_DETAIL"]
 
+
 [tool.coverage.run]
 branch = true
 parallel = true
-source = ["bids_validator"]
+source = ["bids_validator", "tests"]
 omit = [
   "setup.py",
   "*/_version.py",
@@ -77,6 +86,7 @@ exclude_lines = [
   "no cov",
   "if __name__ == .__main__.:",
   "if TYPE_CHECKING:",
+  "pytest.skip",
 ]
 
 # Disable black

src/bids_validator/__main__.py

@@ -0,0 +1,108 @@
+# ruff: noqa: D100
+# ruff: noqa: D103
+
+try:
+    import typer
+except ImportError:
+    print('⚠️ CLI dependencies are not installed. Install "bids_validator[cli]"')
+    raise SystemExit(1) from None
+
+import sys
+from typing import Annotated
+
+from bids_validator import BIDSValidator
+from bids_validator.types.files import FileTree
+
+app = typer.Typer()
+
+
+def walk(tree: FileTree):
+    """Iterate over children of a FileTree and check if they are a directory or file.
+
+    If it's a directory then run again recursively, if it's a file file check the file name is
+    BIDS compliant.
+
+    Parameters
+    ----------
+    tree : FileTree
+        FileTree object to iterate over
+
+    """
+    for child in tree.children.values():
+        if child.is_dir:
+            yield from walk(child)
+        else:
+            yield child
+
+
+def validate(tree: FileTree):
+    """Check if the file path is BIDS compliant.
+
+    Parameters
+    ----------
+    tree : FileTree
+        Full FileTree object to iterate over and check
+
+    """
+    validator = BIDSValidator()
+
+    for file in walk(tree):
+        # The output of the FileTree.relative_path method always drops the initial for the path
+        # which makes it fail the validator.is_bids check. THis may be a Windows specific thing.
+        # This line adds it back.
+        path = f'/{file.relative_path}'
+
+        if not validator.is_bids(path):
+            print(f'{path} is not a valid bids filename')
+
+
+def show_version():
+    """Show bids-validator version."""
+    from . import __version__
+
+    print(f'bids-validator {__version__} (Python {sys.version.split()[0]})')
+
+
+def version_callback(value: bool):
+    """Run the callback for CLI version flag.
+
+    Parameters
+    ----------
+    value : bool
+        value received from --version flag
+
+    Raises
+    ------
+    typer.Exit
+        Exit without any errors
+
+    """
+    if value:
+        show_version()
+        raise typer.Exit()
+
+
+@app.command()
+def main(
+    bids_path: str,
+    verbose: Annotated[bool, typer.Option('--verbose', '-v', help='Show verbose output')] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            '--version',
+            help='Show version',
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    if verbose:
+        show_version()
+
+    root_path = FileTree.read_from_filesystem(bids_path)
+
+    validate(root_path)
+
+
+if __name__ == '__main__':
+    app()

src/bids_validator/types/__init__.py

@@ -0,0 +1 @@
+"""Modules for providing types."""

src/bids_validator/types/files.py

@@ -0,0 +1,126 @@
+"""Types for working with file trees."""
+
+import os
+import posixpath
+import stat
+from functools import cached_property
+from pathlib import Path
+from typing import Union
+
+import attrs
+from typing_extensions import Self  # PY310
+
+__all__ = ('FileTree',)
+
+
+@attrs.define
+class UserDirEntry:
+    """Partial reimplementation of :class:`os.DirEntry`.
+
+    :class:`os.DirEntry` can't be instantiated from Python, but this can.
+    """
+
+    path: str = attrs.field(repr=False, converter=os.fspath)
+    name: str = attrs.field(init=False)
+    _stat: os.stat_result = attrs.field(init=False, repr=False, default=None)
+    _lstat: os.stat_result = attrs.field(init=False, repr=False, default=None)
+
+    def __attrs_post_init__(self) -> None:
+        self.name = os.path.basename(self.path)
+
+    def __fspath__(self) -> str:
+        return self.path
+
+    def stat(self, *, follow_symlinks: bool = True) -> os.stat_result:
+        """Return stat_result object for the entry; cached per entry."""
+        if follow_symlinks:
+            if self._stat is None:
+                self._stat = os.stat(self.path, follow_symlinks=True)
+            return self._stat
+        else:
+            if self._lstat is None:
+                self._lstat = os.stat(self.path, follow_symlinks=False)
+            return self._lstat
+
+    def is_dir(self, *, follow_symlinks: bool = True) -> bool:
+        """Return True if the entry is a directory; cached per entry."""
+        _stat = self.stat(follow_symlinks=follow_symlinks)
+        return stat.S_ISDIR(_stat.st_mode)
+
+    def is_file(self, *, follow_symlinks: bool = True) -> bool:
+        """Return True if the entry is a file; cached per entry."""
+        _stat = self.stat(follow_symlinks=follow_symlinks)
+        return stat.S_ISREG(_stat.st_mode)
+
+    def is_symlink(self) -> bool:
+        """Return True if the entry is a symlink; cached per entry."""
+        _stat = self.stat(follow_symlinks=False)
+        return stat.S_ISLNK(_stat.st_mode)
+
+
+def as_direntry(obj: os.PathLike) -> Union[os.DirEntry, UserDirEntry]:
+    """Convert PathLike into DirEntry-like object."""
+    if isinstance(obj, os.DirEntry):
+        return obj
+    return UserDirEntry(obj)
+
+
+@attrs.define
+class FileTree:
+    """Represent a FileTree with cached metadata."""
+
+    direntry: Union[os.DirEntry, UserDirEntry] = attrs.field(repr=False, converter=as_direntry)
+    parent: Union['FileTree', None] = attrs.field(repr=False, default=None)
+    is_dir: bool = attrs.field(default=False)
+    children: dict[str, 'FileTree'] = attrs.field(repr=False, factory=dict)
+    name: str = attrs.field(init=False)
+
+    def __attrs_post_init__(self):
+        self.name = self.direntry.name
+        self.children = {
+            name: attrs.evolve(child, parent=self) for name, child in self.children.items()
+        }
+
+    @classmethod
+    def read_from_filesystem(
+        cls,
+        direntry: os.PathLike,
+        parent: Union['FileTree', None] = None,
+    ) -> Self:
+        """Read a FileTree from the filesystem.
+
+        Uses :func:`os.scandir` to walk the directory tree.
+        """
+        self = cls(direntry, parent=parent)
+        if self.direntry.is_dir():
+            self.is_dir = True
+            self.children = {
+                entry.name: FileTree.read_from_filesystem(entry, parent=self)
+                for entry in os.scandir(self.direntry)
+            }
+        return self
+
+    def __contains__(self, relpath: os.PathLike) -> bool:
+        parts = Path(relpath).parts
+        if len(parts) == 0:
+            return False
+        child = self.children.get(parts[0], False)
+        return child and (len(parts) == 1 or posixpath.join(*parts[1:]) in child)
+
+    def __fspath__(self):
+        return self.direntry.path
+
+    @cached_property
+    def relative_path(self) -> str:
+        """The path of the current FileTree, relative to the root.
+
+        Follows parents up to the root and joins with POSIX separators (/).
+        Directories include trailing slashes for simpler matching.
+        """
+        if self.parent is None:
+            return ''
+
+        return posixpath.join(
+            self.parent.relative_path,
+            f'{self.name}/' if self.is_dir else self.name,
+        )

tests/__init__.py

@@ -0,0 +1 @@
+"""bids_validator tests."""

tests/conftest.py

@@ -0,0 +1,18 @@
+"""Pytest configuration."""
+
+import importlib.resources
+import os
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(scope='session')
+def examples() -> Path:
+    """Get bids-examples from submodule, allow environment variable override."""
+    ret = os.getenv('BIDS_EXAMPLES')
+    if not ret:
+        ret = importlib.resources.files(__spec__.parent) / 'data' / 'bids-examples'
+        if not any(ret.iterdir()):
+            pytest.skip('bids-examples submodule is not checked out')
+    return Path(ret)

tests/data/bids-examples

@@ -0,0 +1 @@
+"""Tests for bids_validator.types."""

tests/types/__init__.py

@@ -0,0 +1,19 @@
+# ruff: noqa: D100
+
+import attrs
+
+from bids_validator.types.files import FileTree
+
+
+def test_FileTree(examples):
+    """Test the FileTree class."""
+    ds000117 = FileTree.read_from_filesystem(examples / 'ds000117')
+    assert 'sub-01/ses-mri/anat/sub-01_ses-mri_acq-mprage_T1w.nii.gz' in ds000117
+    assert ds000117.children['sub-01'].parent is ds000117
+
+    # Verify that evolving FileTrees creates consistent structures
+    evolved = attrs.evolve(ds000117)
+    assert evolved.children['sub-01'].parent is not ds000117
+    assert evolved.children['sub-01'].parent is evolved
+    assert evolved.children['sub-01'].children['ses-mri'].parent is not ds000117.children['sub-01']
+    assert evolved.children['sub-01'].children['ses-mri'].parent is evolved.children['sub-01']

tests/types/test_files.py

@@ -44,15 +44,20 @@ pass_env =
   NO_COLOR
   CLICOLOR
   CLICOLOR_FORCE
-extras = test
+extras =
+  test
+  cli
 uv_resolution =
   min: lowest-direct
 deps =
   pre: git+https://github.com/bids-standard/bids-specification.git\#subdirectory=tools/schemacode
 
 commands =
-  python -m pytest --doctest-modules --cov . --cov-report xml --cov-report term \
-    --junitxml=test-results.xml -v {posargs}
+  coverage erase
+  coverage run -p -m bids_validator tests/data/bids-examples/ds000117
+  python -m pytest --doctest-modules --cov . --cov-append --cov-report term \
+    --junitxml=test-results.xml {posargs}
+  coverage xml
 
 [testenv:docs]
 description = Build documentation site