[ENH]: Adopt Pydantic for schema validation

docs/api/onthefly.rst

@@ -5,5 +5,5 @@ On-the-fly
    :members:
    :imported-members:
 
-.. automodule:: junifer.onthefly.brainprint
+.. automodule:: junifer.onthefly._brainprint
    :members:

docs/builtin.rst

@@ -158,16 +158,16 @@ Available
        | (subject-native or other template spaces)
      - Done
      - 0.0.4
-   * - ``Smoothing``
+   * - :class:`.Smoothing`
      - | Apply smoothing to data, particularly useful when dealing with
        | ``fMRIPrep``-ed data
      - In Progress
      - :gh:`161`
-   * - ``TemporalSlicer``
+   * - :class:`.TemporalSlicer`
      - Slice ``BOLD`` data temporally
      - | Done
      - :gh:`443`
-   * - ``TemporalFilter``
+   * - :class:`.TemporalFilter`
      - Filter (clean) ``BOLD`` data temporally
      - | Done
      - :gh:`432`

docs/changes/newsfragments/364.enh

@@ -0,0 +1 @@
+Adopt Pydantic for user-facing core objects to perform automatic validation using typing annotations by `Synchon Mandal`_

docs/conf.py

@@ -65,6 +65,8 @@
     "sphinx_copybutton",  # copy button for code blocks
     "sphinxcontrib.mermaid",  # mermaid support
     "sphinxcontrib.towncrier.ext",  # towncrier fragment support
+    "sphinxcontrib.autodoc_pydantic",  # autodoc support for pydantic models
+    "enum_tools.autoenum",  # enum support
 ]
 
 if use_multiversion:
@@ -97,6 +99,8 @@
     ("py:class", "pipeline.Pipeline"),  # nilearn
     ("py:obj", "neurokit2.*"),  # ignore neurokit2
     ("py:obj", "datalad.*"),  # ignore datalad
+    ("py:obj", "junifer.*"),  # ignore junifer internal
+    ("py:class", "annotated_types.*")  # ignore pydantic annotated types
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -154,6 +158,7 @@
     "pandas": ("https://pandas.pydata.org/pandas-docs/dev", None),
     # "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "pydantic": ("https://docs.pydantic.dev/latest/", None),
 }
 
 # -- sphinx.ext.extlinks configuration ---------------------------------------

docs/extending/datagrabber.rst

@@ -140,29 +140,24 @@ With the variables defined above, we can create our DataGrabber and name it
 
     from pathlib import Path
 
-    from junifer.datagrabber import PatternDataGrabber
+    from junifer.datagrabber import PatternDataGrabber, DataType
+    from junifer.typing import DataGrabberPatterns
 
 
     class ExampleBIDSDataGrabber(PatternDataGrabber):
-        def __init__(self, datadir: str | Path) -> None:
-            types = ["T1w", "BOLD"]
-            patterns = {
-                "T1w": {
-                    "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
-                    "space": "native",
-                },
-                "BOLD": {
-                    "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
-                    "space": "MNI152NLin6Asym",
-                },
-            }
-            replacements = ["subject", "session"]
-            super().__init__(
-                datadir=datadir,
-                types=types,
-                patterns=patterns,
-                replacements=replacements,
-            )
+
+        types: list[DataType] = [DataType.T1w, DataType.BOLD]
+        patterns: DataGrabberPatterns = {
+            "T1w": {
+                "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
+                "space": "native",
+            },
+            "BOLD": {
+                "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
+                "space": "MNI152NLin6Asym",
+            },
+        }
+        replacements: list[str] = ["subject", "session"]
 
 Our DataGrabber is ready to be used by ``junifer``. However, it is still unknown
 to the library. We need to register it in the library. To do so, we need to
@@ -175,29 +170,24 @@ use the :func:`.register_datagrabber` decorator.
 
     from junifer.api.decorators import register_datagrabber
     from junifer.datagrabber import PatternDataGrabber
+    from junifer.typing import DataGrabberPatterns
 
 
     @register_datagrabber
     class ExampleBIDSDataGrabber(PatternDataGrabber):
-        def __init__(self, datadir: str | Path) -> None:
-            types = ["T1w", "BOLD"]
-            patterns = {
-                "T1w": {
-                    "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
-                    "space": "native",
-                },
-                "BOLD": {
-                    "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
-                    "space": "MNI152NLin6Asym",
-                },
-            }
-            replacements = ["subject", "session"]
-            super().__init__(
-                datadir=datadir,
-                types=types,
-                patterns=patterns,
-                replacements=replacements,
-            )
+
+        types: list[DataType] = [DataType.T1w, DataType.BOLD]
+        patterns: DataGrabberPatterns = {
+            "T1w": {
+                "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
+                "space": "native",
+            },
+            "BOLD": {
+                "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
+                "space": "MNI152NLin6Asym",
+            },
+        }
+        replacements: list[str] = ["subject", "session"]
 
 
 Now, we can use our DataGrabber in ``junifer``, by setting the ``datagrabber``
@@ -259,35 +249,30 @@ And we can create our DataGrabber:
 
 .. code-block:: python
 
+    from pathlib import Path
+
     from junifer.api.decorators import register_datagrabber
     from junifer.datagrabber import PatternDataladDataGrabber
+    from pydantic import HttpUrl
 
 
     @register_datagrabber
     class ExampleBIDSDataGrabber(PatternDataladDataGrabber):
-        def __init__(self) -> None:
-            types = ["T1w", "BOLD"]
-            patterns = {
-                "T1w": {
-                    "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
-                    "space": "native",
-                },
-                "BOLD": {
-                    "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
-                    "space": "MNI152NLin6Asym",
-                },
-            }
-            replacements = ["subject", "session"]
-            uri = "https://gin.g-node.org/juaml/datalad-example-bids"
-            rootdir = "example_bids_ses"
-            super().__init__(
-                datadir=None,
-                uri=uri,
-                rootdir=rootdir,
-                types=types,
-                patterns=patterns,
-                replacements=replacements,
-            )
+
+        uri: HttpUrl = HttpUrl("https://gin.g-node.org/juaml/datalad-example-bids")
+        types: list[DataType] = [DataType.T1w, DataType.BOLD]
+        patterns: DataGrabberPatterns = {
+            "T1w": {
+                "pattern": "{subject}/{session}/anat/{subject}_{session}_T1w.nii.gz",
+                "space": "native",
+            },
+            "BOLD": {
+                "pattern": "{subject}/{session}/func/{subject}_{session}_task-rest_bold.nii.gz",
+                "space": "MNI152NLin6Asym",
+            },
+        }
+        replacements: list[str] = ["subject", "session"]
+        rootdir: Path = Path("example_bids_ses")
 
 This approach can be used directly from the YAML, like so:
 
@@ -376,8 +361,8 @@ need to implement the following methods:
 
 .. note::
 
-   The ``__init__`` method could also be implemented, but it is not mandatory.
-   This is required if the DataGrabber requires any extra parameter.
+   If the DataGrabber requires any extra parameter, they could be defined as
+   class attributes.
 
 We will now implement our BIDS example with this method.
 
@@ -494,8 +479,8 @@ more information about the format of the confounds file. Thus, the
 ``BOLD.confounds`` element is a dictionary with the following keys:
 
 - ``path``: the path to the confounds file.
-- ``format``: the format of the confounds file. Currently, this can be either
-  ``fmriprep`` or ``adhoc``.
+- ``format``: the format of the confounds file. Check :enum:`.ConfoundsFormat`
+  for options.
 
 The ``fmriprep`` format corresponds to the format of the confounds files
 generated by `fMRIPrep`_. The ``adhoc`` format corresponds to a format that is

docs/extending/dependencies.rst

@@ -46,7 +46,7 @@ by having a class attribute like so:
 
     _EXT_DEPENDENCIES: ClassVar[ExternalDependencies] = [
         {
-            "name": "afni",
+            "name": ExtDep.AFNI,
             "commands": ["3dReHo", "3dAFNItoNIFTI"],
         },
     ]
@@ -55,7 +55,7 @@ The above example is taken from the class which computes regional homogeneity
 (ReHo) using AFNI. The general pattern is that you need to have the value of
 ``_EXT_DEPENDENCIES`` as a list of dictionary with two keys:
 
-* ``name`` (str) : lowercased name of the toolbox
+* ``name`` (:enum:`.ExtDep`) : name of the toolbox
 * ``commands`` (list of str) : actual names of the commands you need to use
 
 This is simple but powerful as we will see in the following sub-sections.
@@ -81,30 +81,28 @@ that it shows the problem a bit better and how we solve it:
         _CONDITIONAL_DEPENDENCIES: ClassVar[ConditionalDependencies] = [
             {
                 "using": "fsl",
-                "depends_on": FSLWarper,
+                "depends_on": [FSLWarper],
             },
             {
                 "using": "ants",
-                "depends_on": ANTsWarper,
+                "depends_on": [ANTSWarper],
             },
             {
                 "using": "auto",
                 "depends_on": [FSLWarper, ANTsWarper],
             },
         ]
 
-        def __init__(
-            self, using: str, reference: str, on: Union[List[str], str]
-        ) -> None:
-            # validation and setting up
-            ...
+        using: str
+        reference: str
+        on: List[DataType]
 
 
 Here, you see a new class attribute ``_CONDITIONAL_DEPENDENCIES`` which is a
 list of dictionaries with two keys:
 
 * ``using`` (str) : lowercased name of the toolbox
-* ``depends_on`` (object or list of objects) : a class or list of classes which \
+* ``depends_on`` (list of objects) : list of classes which \
   implements the particular tool's use
 
 It is mandatory to have the ``using`` positional argument in the constructor in
@@ -128,7 +126,7 @@ similar. ``FSLWarper`` looks like this (only the relevant part is shown here):
 
         _EXT_DEPENDENCIES: ClassVar[ExternalDependencies] = [
             {
-                "name": "fsl",
+                "name": ExtDep.FSL,
                 "commands": ["flirt", "applywarp"],
             },
         ]