Add docstring linting

.pre-commit-config.yaml

@@ -8,23 +8,33 @@ repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
       rev: v5.0.0
       hooks:
+          - id: check-added-large-files
           - id: check-docstring-first
           - id: check-executables-have-shebangs
+          - id: check-case-conflict
           - id: check-merge-conflict
+          - id: check-symlinks
+          - id: check-yaml
           - id: check-toml
+          - id: debug-statements
           - id: end-of-file-fixer
           - id: mixed-line-ending
             args: [--fix=lf]
+          #- id: name-tests-test
+          #  args: ["--pytest-test-first"]
           - id: requirements-txt-fixer
           - id: trailing-whitespace
+    - repo: https://github.com/pre-commit/pygrep-hooks
+      rev: v1.10.0
+      hooks:
+        - id: rst-backticks
+        - id: rst-directive-colons
+        - id: rst-inline-touching-normal
     - repo: https://github.com/astral-sh/ruff-pre-commit
       rev: v0.9.9
       hooks:
         - id: ruff
-    - repo: https://github.com/psf/black
-      rev: 25.1.0
-      hooks:
-          - id: black
+        - id: ruff-format
     - repo: https://github.com/pre-commit/mirrors-mypy
       rev: v1.15.0
       hooks:

datashuttle/configs/canonical_configs.py

@@ -1,5 +1,4 @@
-"""
-This module contains all information for the required
+"""Contains all information for the required
 format of the configs class. This is clearly defined
 as configs can be provided from file or input dynamically
 and so careful checks must be done.
@@ -32,8 +31,7 @@
 
 
 def get_canonical_configs() -> dict:
-    """
-    The only permitted types for DataShuttle
+    """The only permitted types for DataShuttle
     config values.
     """
     canonical_configs = {
@@ -48,8 +46,7 @@ def get_canonical_configs() -> dict:
 
 
 def keys_str_on_file_but_path_in_class() -> list[str]:
-    """
-    All configs which are paths are converted to pathlib.Path
+    """All configs which are paths are converted to pathlib.Path
     objects on load. This list indicates which config entries
     are to be converted to Path.
     """
@@ -65,8 +62,7 @@ def keys_str_on_file_but_path_in_class() -> list[str]:
 
 
 def check_dict_values_raise_on_fail(config_dict: Configs) -> None:
-    """
-    Central function for performing checks on a
+    """Central function for performing checks on a
     DataShuttle Configs UserDict class. This should
     be run after any change to the configs (e.g.
     make_config_file, update_config_file, supply_config_file).
@@ -75,8 +71,9 @@ def check_dict_values_raise_on_fail(config_dict: Configs) -> None:
 
     Parameters
     ----------
+    config_dict
+        datashuttle config UserDict
 
-    config_dict : datashuttle config UserDict
     """
     canonical_dict = get_canonical_configs()
 
@@ -143,8 +140,7 @@ def check_dict_values_raise_on_fail(config_dict: Configs) -> None:
 
 
 def raise_on_bad_local_only_project_configs(config_dict: Configs) -> None:
-    """
-    There is no circumstance where one of `central_path` and `connection_method`
+    """There is no circumstance where one of `central_path` and `connection_method`
     should be set and not the other. Either both are set ('full' project) or
     neither are ('local only' project). Check this assumption here.
     """
@@ -160,6 +156,9 @@ def raise_on_bad_local_only_project_configs(config_dict: Configs) -> None:
 
 
 def local_only_configs_are_none(config_dict: Configs) -> list[bool]:
+    """Check if the central_path and connection_method config options
+    are set to `None`.
+    """
     return [
         config_dict[key] is None
         for key in ["central_path", "connection_method"]
@@ -170,14 +169,12 @@ def raise_on_bad_path_syntax(
     path_name: str,
     path_type: str,
 ) -> None:
-    """
-    Error if some common, unsupported patterns are observed
+    """Error if some common, unsupported patterns are observed
     (e.g. ~, .) for path.
     """
     if path_name[0] == "~":
         utils.log_and_raise_error(
-            f"{path_type} must contain the full folder path "
-            "with no ~ syntax.",
+            f"{path_type} must contain the full folder path with no ~ syntax.",
             ConfigError,
         )
 
@@ -192,13 +189,10 @@ def raise_on_bad_path_syntax(
 
 
 def check_config_types(config_dict: Configs) -> None:
-    """
-    Check the type of passed configs matches the canonical types.
-    """
+    """Check the type of passed configs matches the canonical types."""
     required_types = get_canonical_configs()
 
     for key in config_dict.keys():
-
         expected_type = required_types[key]
         try:
             typeguard.check_type(config_dict[key], expected_type)
@@ -217,8 +211,7 @@ def check_config_types(config_dict: Configs) -> None:
 
 
 def get_tui_config_defaults() -> Dict:
-    """
-    Get the default settings for the datatype checkboxes
+    """Get the default settings for the datatype checkboxes
     in the TUI.
 
     Two sets are maintained (one for creating,
@@ -247,7 +240,6 @@ def get_tui_config_defaults() -> Dict:
 
     # Fill all datatype options
     for broad_key in get_broad_datatypes():
-
         settings["tui"]["create_checkboxes_on"][broad_key] = {  # type: ignore
             "on": True,
             "displayed": True,
@@ -271,12 +263,12 @@ def get_tui_config_defaults() -> Dict:
 
 
 def get_name_templates_defaults() -> Dict:
+    """Get the default values for name_templates."""
     return {"name_templates": {"on": False, "sub": None, "ses": None}}
 
 
 def get_persistent_settings_defaults() -> Dict:
-    """
-    Persistent settings are settings that are maintained
+    """Persistent settings are settings that are maintained
     across sessions. Currently, persistent settings for
     both the API and TUI are stored in the same place.
 
@@ -292,21 +284,20 @@ def get_persistent_settings_defaults() -> Dict:
 
 
 def get_datatypes() -> List[str]:
-    """
-    Canonical list of datatype flags based on NeuroBlueprint.
+    """Canonical list of datatype flags based on NeuroBlueprint.
 
     This must be kept up to date with the datatypes in the NeuroBlueprint specification.
     """
     return get_broad_datatypes() + quick_get_narrow_datatypes()
 
 
 def get_broad_datatypes():
+    """Return a list of broad datatypes."""
     return ["ephys", "behav", "funcimg", "anat"]
 
 
 def get_narrow_datatypes():
-    """
-    Return the narrow datatype associated with each broad datatype.
+    """Return the narrow datatype associated with each broad datatype.
     The mapping between broad and narrow datatypes is required for validation.
     """
     return {
@@ -336,8 +327,7 @@ def get_narrow_datatypes():
 
 
 def quick_get_narrow_datatypes():
-    """
-    A convenience wrapper around `get_narrow_datatypes()`
+    """A convenience wrapper around `get_narrow_datatypes()`
     to quickly get a list of all narrow datatypes.
     """
     all_narrow_datatypes = get_narrow_datatypes()
@@ -351,8 +341,7 @@ def quick_get_narrow_datatypes():
 
 
 def in_place_update_settings_for_narrow_datatype(settings: dict):
-    """
-    In versions < v0.6.0, only 'broad' datatypes were implemented
+    """In versions < v0.6.0, only 'broad' datatypes were implemented
     and available in the TUI. Since, 'narrow' datatypes are introduced
     and datatype tui can be set to be both on / off but also
     displayed / not displayed.

datashuttle/configs/canonical_folders.py

@@ -11,8 +11,7 @@
 
 
 def get_datatype_folders() -> dict:
-    """
-    This function holds the canonical folders
+    """Holds the canonical folders
     managed by datashuttle.
 
     Notes
@@ -26,12 +25,17 @@ def get_datatype_folders() -> dict:
     The value is a Folder() class instance with
     the required fields
 
-    name : The display name for the datatype, that will
+    Parameters
+    ----------
+    name
+        The display name for the datatype, that will
         be used for making and transferring files in practice.
         This should always match the canonical name, but left as
         an option for rare cases in which advanced users want to change it.
 
-    level : "sub" or "ses", level to make the folder at.
+    level
+        "sub" or "ses", level to make the folder at.
+
     """
     return {
         datatype: Folder(name=datatype, level="ses")
@@ -40,9 +44,8 @@ def get_datatype_folders() -> dict:
 
 
 def get_non_sub_names() -> List[str]:
-    """
-    Get all arguments that are not allowed at the
-    subject level for data transfer, i.e. as sub_names
+    """Get all arguments that are not allowed at the
+    subject level for data transfer, i.e. as sub_names.
     """
     return [
         "all_ses",
@@ -53,9 +56,8 @@ def get_non_sub_names() -> List[str]:
 
 
 def get_non_ses_names() -> List[str]:
-    """
-    Get all arguments that are not allowed at the
-    session level for data transfer, i.e. as ses_names
+    """Get all arguments that are not allowed at the
+    session level for data transfer, i.e. as ses_names.
     """
     return [
         "all_sub",
@@ -66,28 +68,26 @@ def get_non_ses_names() -> List[str]:
 
 
 def canonical_reserved_keywords() -> List[str]:
-    """
-    Key keyword arguments that are passed to `sub_names` or
-    `ses_names` but that we
+    """Key keyword arguments that are passed to `sub_names` or
+    `ses_names`.
     """
     return get_non_sub_names() + get_non_ses_names()
 
 
 def get_top_level_folders() -> List[TopLevelFolder]:
+    """Return a list of the different top level folder names."""
     return ["rawdata", "derivatives"]
 
 
 def get_datashuttle_path() -> Path:
-    """
-    Get the datashuttle path where all project
+    """Get the datashuttle path where all project
     configs are stored.
     """
     return Path.home() / ".datashuttle"
 
 
 def get_project_datashuttle_path(project_name: str) -> Tuple[Path, Path]:
-    """
-    Get the datashuttle path for the project,
+    """Get the datashuttle path for the project,
     where configuration files are stored.
     Also, return a temporary path in this for logging in
     some cases where local_path location is not clear.

datashuttle/configs/canonical_tags.py

@@ -1,6 +1,5 @@
 def tags(tag_name: str) -> str:
-    """
-    Centralised function to get the tags used
+    """Centralised function to get the tags used
     in subject / session name processing. If changing
     the formatting of these tags, it is only required
     to change the dict values here.