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.11.12
       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.16.0
       hooks:

datashuttle/configs/canonical_configs.py

@@ -1,12 +1,10 @@
-"""
-This module 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.
-
-If adding a new config, first add the key to
-get_canonical_configs() and type to
-get_canonical_configs()
+"""Contains all information defining the required format of the Configs class.
+
+This format is clearly specified because configs can be supplied
+either from a file or dynamically, so careful validation is required.
+
+If adding a new config key:
+- First add the key to `get_canonical_configs()` and define its type in the same function
 """
 
 from __future__ import annotations
@@ -31,10 +29,7 @@
 
 
 def get_canonical_configs() -> dict:
-    """
-    The only permitted types for DataShuttle
-    config values.
-    """
+    """Return the only permitted types for DataShuttle config values."""
     canonical_configs = {
         "local_path": Union[str, Path],
         "central_path": Optional[Union[str, Path]],
@@ -47,10 +42,9 @@ 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
-    objects on load. This list indicates which config entries
-    are to be converted to Path.
+    """Return a list of all config keys that are paths but stored as str in the file.
+
+    These are converted to pathlib.Path objects when loaded.
     """
     return [
         "local_path",
@@ -64,18 +58,18 @@ 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
-    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).
+    """Perform checks on a DataShuttle Configs UserDict class.
 
-    This will raise assert if condition is not met.
+    This should be run after any change to the configs
+    (e.g. make_config_file, update_config_file, supply_config_file).
+
+    This will raise an error if a condition is not met.
 
     Parameters
     ----------
+    config_dict
+        datashuttle config UserDict
 
-    config_dict : datashuttle config UserDict
     """
     canonical_dict = get_canonical_configs()
 
@@ -142,10 +136,10 @@ 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`
-    should be set and not the other. Either both are set ('full' project) or
-    neither are ('local only' project). Check this assumption here.
+    """Check that both or neither of `central_path` and `connection_method` are set.
+
+    There is no circumstance where one is set and not the other. Either both are set
+    ('full' project) or both are `None` ('local only' project).
     """
     params_are_none = local_only_configs_are_none(config_dict)
 
@@ -159,6 +153,7 @@ def raise_on_bad_local_only_project_configs(config_dict: Configs) -> None:
 
 
 def local_only_configs_are_none(config_dict: Configs) -> list[bool]:
+    """Check whether `central_path` and `connection_method` are both set to None."""
     return [
         config_dict[key] is None
         for key in ["central_path", "connection_method"]
@@ -169,14 +164,10 @@ def raise_on_bad_path_syntax(
     path_name: str,
     path_type: str,
 ) -> None:
-    """
-    Error if some common, unsupported patterns are observed
-    (e.g. ~, .) for path.
-    """
+    """Raise error if path contains unsupported patterns (e.g. ~, .)."""
     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,
         )
 
@@ -191,13 +182,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)
@@ -216,14 +204,12 @@ def check_config_types(config_dict: Configs) -> None:
 
 
 def get_tui_config_defaults() -> Dict:
-    """
-    Get the default settings for the datatype checkboxes
-    in the TUI.
+    """Return the default settings for the datatype checkboxes in the TUI.
 
-    Two sets are maintained (one for creating,
-    one for transfer) which have different defaults.
+    Two sets are maintained (one for  checkboxes on the create tab,
+    the other for transfer tab) which have different defaults.
     By default, all broad datatype checkboxes are displayed,
-    and narrow are turned off.
+    and narrow datatypes are hidden and turned off.
     """
     settings = {
         "tui": {
@@ -247,7 +233,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,18 +256,16 @@ def get_tui_config_defaults() -> Dict:
 
 
 def get_name_templates_defaults() -> Dict:
+    """Return 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
-    across sessions. Currently, persistent settings for
-    both the API and TUI are stored in the same place.
+    """Return the default persistent settings maintained across sessions.
 
-    Currently, settings for the working top level folder,
-    TUI checkboxes and name templates (i.e. regexp
-    validation for sub and ses names) are stored.
+    Currently, these include settings for both the API and TUI, such as the
+    working top level folder, TUI checkboxes, and name templates
+    (i.e. regexp validation for sub and ses names).
     """
     settings = {}
     settings.update(get_tui_config_defaults())
@@ -292,21 +275,21 @@ def get_persistent_settings_defaults() -> Dict:
 
 
 def get_datatypes() -> List[str]:
-    """
-    Canonical list of datatype flags based on NeuroBlueprint.
+    """Return 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 {
@@ -337,9 +320,9 @@ def get_narrow_datatypes():
 
 
 def quick_get_narrow_datatypes():
-    """
-    A convenience wrapper around `get_narrow_datatypes()`
-    to quickly get a list of all narrow datatypes.
+    """Return a flat list of all narrow datatypes.
+
+    This is a convenience wrapper around `get_narrow_datatypes()`.
     """
     all_narrow_datatypes = get_narrow_datatypes()
     top_level_keys = list(all_narrow_datatypes.keys())
@@ -352,7 +335,8 @@ def quick_get_narrow_datatypes():
 
 
 def in_place_update_narrow_datatypes_if_required(user_settings: dict):
-    """
+    """Update legacy settings with the new version format.
+
     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
@@ -389,7 +373,9 @@ def in_place_update_narrow_datatypes_if_required(user_settings: dict):
                 dtype in user_settings["tui"]["transfer_checkboxes_on"]
                 for dtype in all_narrow_datatypes
             ]
-        ), "Somehow there are datatypes missing in `transfer_checkboxes_on` but not `create_checkboxes_on`"
+        ), (
+            "Somehow there are datatypes missing in `transfer_checkboxes_on` but not `create_checkboxes_on`"
+        )
 
     if has_narrow_datatypes and is_not_missing_any_narrow_datatypes:
         return
@@ -421,15 +407,12 @@ def in_place_update_narrow_datatypes_if_required(user_settings: dict):
     # Copy any datatype information that exists. Broad datatypes will all be there
     # but some narrow datatypes might be missing.
     for checkbox_type in ["create_checkboxes_on", "transfer_checkboxes_on"]:
-
         datatypes_that_user_has = list(
             user_settings["tui"][checkbox_type].keys()
         )
 
         for dtype in get_datatypes():
-
             if dtype in datatypes_that_user_has:
-
                 if has_narrow_datatypes:
                     new_checkbox_configs[checkbox_type][dtype] = user_settings[
                         "tui"

datashuttle/configs/canonical_folders.py

@@ -11,9 +11,7 @@
 
 
 def get_datatype_folders() -> dict:
-    """
-    This function holds the canonical folders
-    managed by datashuttle.
+    """Return the canonical folders managed by datashuttle.
 
     Notes
     -----
@@ -24,14 +22,19 @@ def get_datatype_folders() -> dict:
     kept in case this changes.
 
     The value is a Folder() class instance with
-    the required fields
+    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 +43,9 @@ 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
+    """Return all arguments that are not allowed at the subject level.
+
+    These are invalid as `sub_names` for data transfer.
     """
     return [
         "all_ses",
@@ -53,10 +56,7 @@ 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
-    """
+    """Return all arguments that are not allowed at the session level."""
     return [
         "all_sub",
         "all_non_sub",
@@ -66,34 +66,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
-    """
+    """Return key keyword arguments 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 canonical top level folder names."""
     return ["rawdata", "derivatives"]
 
 
 def get_datashuttle_path() -> Path:
-    """
-    Get the datashuttle path where all project
-    configs are stored.
-    """
+    """Return 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,
-    where configuration files are stored.
-    Also, return a temporary path in this for logging in
-    some cases where local_path location is not clear.
+    """Return the datashuttle config path for the project.
 
-    The datashuttle configuration path is stored in the user home
-    folder.
+    Also returns a temporary logging path used in cases when
+    the `local_path` is not yet defined. The base configuration
+    path is the user home directory.
     """
     base_path = get_datashuttle_path() / project_name
     temp_logs_path = base_path / "temp_logs"