Add pydocstyle to pre-commit for consistent docstrings

.pre-commit-config.yaml

@@ -24,3 +24,11 @@ repos:
   - id: codespell
     additional_dependencies:
     - tomli
+
+- repo: https://github.com/pycqa/pydocstyle
+  rev: 6.3.0
+  hooks:
+  - id: pydocstyle
+    args:
+      - --convention=numpy
+      - --add-ignore=D1

src/neuroconv/baseextractorinterface.py

@@ -8,9 +8,7 @@
 
 
 class BaseExtractorInterface(BaseTemporalAlignmentInterface, ABC):
-    """
-    Abstract class defining the structure of all Extractor-based Interfaces.
-    """
+    """Abstract class defining the structure of all Extractor-based Interfaces."""
 
     # Manually override any of these attributes in a subclass if needed.
     # Note that values set at the level of class definition are called upon import.

src/neuroconv/nwbconverter.py

@@ -95,7 +95,10 @@ def get_metadata_schema(self) -> dict:
         return metadata_schema
 
     def get_metadata(self) -> DeepDict:
-        """Auto-fill as much of the metadata as possible. Must comply with metadata schema."""
+        """Auto-fill as much of the metadata as possible.
+
+        Must comply with metadata schema.
+        """
         metadata = get_default_nwbfile_metadata()
         for interface in self.data_interface_objects.values():
             interface_metadata = interface.get_metadata()
@@ -142,8 +145,7 @@ def validate_conversion_options(self, conversion_options: dict[str, dict]):
             print("conversion_options is valid!")
 
     def create_nwbfile(self, metadata: Optional[dict] = None, conversion_options: Optional[dict] = None) -> NWBFile:
-        """
-        Create and return an in-memory pynwb.NWBFile object with this interface's data added to it.
+        """Create and return an in-memory pynwb.NWBFile object with this interface's data added to it.
 
         Parameters
         ----------
@@ -185,8 +187,7 @@ def run_conversion(
         backend_configuration: Optional[HDF5BackendConfiguration] = None,
         conversion_options: Optional[dict] = None,
     ) -> None:
-        """
-        Run the NWB conversion over all the instantiated data interfaces.
+        """Run the NWB conversion over all the instantiated data interfaces.
 
         Parameters
         ----------
@@ -213,7 +214,6 @@ def run_conversion(
             Similar to source_data, a dictionary containing keywords for each interface for which non-default
             conversion specification is requested.
         """
-
         if nwbfile_path is None:
             warnings.warn(  # TODO: remove on or after 2024/12/26
                 "Using Converter.run_conversion without specifying nwbfile_path is deprecated. To create an "
@@ -260,8 +260,7 @@ def get_default_backend_configuration(
         nwbfile: NWBFile,
         backend: Literal["hdf5", "zarr"] = "hdf5",
     ) -> Union[HDF5BackendConfiguration, ZarrBackendConfiguration]:
-        """
-        Fill and return a default backend configuration to serve as a starting point for further customization.
+        """Fill and return a default backend configuration to serve as a starting point for further customization.
 
         Parameters
         ----------

src/neuroconv/utils/checks.py

@@ -5,9 +5,11 @@
 
 
 def calculate_regular_series_rate(series: np.ndarray, tolerance_decimals: int = 6) -> Optional[Real]:
-    """Calculates the rate of a series as the difference between all consecutive points.
+    """Calculate the rate of a series as the difference between all consecutive points.
+
     If the difference between all time points are all the same value, then the value of
-    rate is a scalar otherwise it is None."""
+    rate is a scalar otherwise it is None.
+    """
     diff_ts = np.diff(series)
     rounded_diff_ts = diff_ts.round(decimals=tolerance_decimals)
     uniq_diff_ts = np.unique(rounded_diff_ts)

src/neuroconv/utils/dict.py

@@ -17,8 +17,7 @@ class NoDatesSafeLoader(yaml.SafeLoader):
 
     @classmethod
     def remove_implicit_resolver(cls, tag_to_remove):
-        """
-        Remove implicit resolvers for a particular tag.
+        """Remove implicit resolvers for a particular tag.
 
         Takes care not to modify resolvers in super classes.
         Solution taken from https://stackoverflow.com/a/37958106/11483674
@@ -57,8 +56,7 @@ def exist_dict_in_list(d, ls):
 
 
 def append_replace_dict_in_list(ls, d, compare_key, list_dict_deep_update: bool = True, remove_repeats: bool = True):
-    """
-    Update the list ls with the dict d.
+    """Update the list ls with the dict d.
 
     Cases:
 
@@ -115,8 +113,7 @@ def dict_deep_update(
     compare_key: str = "name",
     list_dict_deep_update: bool = True,
 ) -> collections.abc.Mapping:
-    """
-    Perform an update to all nested keys of dictionary d(input) from dictionary u(updating dict).
+    """Perform an update to all nested keys of dictionary d(input) from dictionary u(updating dict).
 
     Parameters
     ----------
@@ -174,7 +171,6 @@ def dict_deep_update(
     d: dict
         return the updated dictionary
     """
-
     dict_to_update, dict_with_update_values = d, u
     if not isinstance(dict_to_update, collections.abc.Mapping):
         warnings.warn("input to update should be a dict, returning output")
@@ -206,7 +202,7 @@ def dict_deep_update(
 
 
 class DeepDict(defaultdict):
-    """A defaultdict of defaultdicts"""
+    """A defaultdict of defaultdicts."""
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(lambda: DeepDict(), *args, **kwargs)
@@ -222,26 +218,14 @@ def deep_update(self, other: Optional[Union[dict, "DeepDict"]] = None, **kwargs)
                 self[key] = value
 
     def to_dict(self) -> dict:
-        """Turn a DeepDict into a normal dictionary"""
+        """Turn a DeepDict into a normal dictionary."""
 
         def _to_dict(d: Union[dict, "DeepDict"]) -> dict:
             return {key: _to_dict(value) for key, value in d.items()} if isinstance(d, dict) else d
 
         return _to_dict(self)
 
     def __deepcopy__(self, memodict={}):
-        """
-
-        Parameters
-        ----------
-        memodict: dict
-            unused
-
-        Returns
-        -------
-        DeepDict
-
-        """
         return DeepDict(deepcopy(self.to_dict()))
 
     def __repr__(self) -> str:

src/neuroconv/utils/json_schema.py

@@ -69,7 +69,7 @@ def get_base_schema(
     return base_schema
 
 
-def get_schema_from_method_signature(method: Callable, exclude: Optional[list[str]] = None) -> dict:
+def get_schema_from_method_signature(method: Callable, exclude: Optional[list[str]] = None) -> dict:  # noqa: D401
     """Deprecated version of `get_json_schema_from_method_signature`."""
     message = (
         "The method `get_schema_from_method_signature` is now named `get_json_schema_from_method_signature`."
@@ -81,8 +81,7 @@ def get_schema_from_method_signature(method: Callable, exclude: Optional[list[st
 
 
 def get_json_schema_from_method_signature(method: Callable, exclude: Optional[list[str]] = None) -> dict:
-    """
-    Get the equivalent JSON schema for a signature of a method.
+    """Get the equivalent JSON schema for a signature of a method.
 
     Also uses `docstring_parser` (NumPy style) to attempt to find descriptions for the arguments.
 
@@ -165,8 +164,7 @@ def _copy_without_title_keys(d: Any, /) -> Optional[dict]:
 
 
 def fill_defaults(schema: dict, defaults: dict, overwrite: bool = True):
-    """
-    Insert the values of the defaults dict as default values in the schema in place.
+    """Insert the values of the defaults dict as default values in the schema in place.
 
     Parameters
     ----------
@@ -190,8 +188,7 @@ def fill_defaults(schema: dict, defaults: dict, overwrite: bool = True):
 
 
 def unroot_schema(schema: dict):
-    """
-    Modify a json-schema dictionary to make it not root.
+    """Modify a json-schema dictionary to make it not root.
 
     Parameters
     ----------

src/neuroconv/utils/path.py

@@ -4,8 +4,7 @@
 
 
 def infer_path(path: str) -> Union[PureWindowsPath, Path]:
-    """
-    Infers and returns the appropriate path object based on the path string.
+    r"""Infers and returns the appropriate path object based on the path string.
 
     Parameters
     ----------

src/neuroconv/utils/str_utils.py

@@ -2,9 +2,7 @@
 
 
 def human_readable_size(size_bytes: int, binary: bool = False) -> str:
-    """
-    Convert a file size given in bytes to a human-readable format using division
-    and remainder instead of iteration.
+    """Convert a file size given in bytes to a human-readable format using division and remainder instead of iteration.
 
     Parameters
     ----------