Add docstring linting (#493)

* Removing type hints from all docstrings

* formatting parameter headings

* Removing black + configuring ruff using movement repo config

* moving per-file-ignores for __init__.py to the list in tool.ruff.lint

* run pre-commit

* enabling ruff-format

* fixing pre-commit errors for test_configs and test_validation_unit

* disabling pre-commit

* Editing all test files to comply with linting rules

* ignoring rule D100 for now

* fixed datashuttle_functions.py

* fixing datashuttle_class

* fixing utils

* fixed tui

* fixed configs

* run pre-commit

* renaming TCH to TC

* moving Iterable import into type checking block to comply with TC003

* re-arranging rules

* Adding informative comment about ruff config

* Filling in PLACEHOLDER dosctrings in configs and utils

* syncing branch with main and adding PLACEHOLDER docstring

* enabling ruff-format

* pre-commit autofix

* pre-commit autofix

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix linting.

* Fixing validation as a test.

* Rewrite config_class.py

* Update canonical_folders.py

* Update canonical_configs.py

* Update load_configs.py

* Update load_configs.py

* Update datashuttle_class.py

* Update ds_logger.py

* Update decorators.py

* Update data_transfer.py

* Update rlcone.py.

* Update getters.py

* update formatting.py

* update folders.py

* Update folder_class.py

* Update folder_utils.py

* Update ssh.py

* Update validate.py

* Update tooltips.py

* Update app.py

* Update custom widgets.

* Update interface.py

* Update decorators.py

* Update tui_validators.py

* Update configs_content.py

* Update validate_content.py

* Update create_folders.py.

* Update transfer_status_tree.py

* Update logging.py.

* Update transfer.py

* Update new_project.py

* update get_help.py

* Update validate_at_path.py

* Update settings.py

* Update project_selector.py

* Update project_manager.py

* Update setup_ssh.py

* Update modal_dialogs.py

* Update datatypes.py

* Update create_folder_settings.py

* Add Returns sections.

* Fix tests and remove PLACEHOLDER in tests.

---------

Co-authored-by: JoeZiminski <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

.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"