ci: Add pydocstyle to pre-commit hooks (#505)

.pre-commit-config.yaml

@@ -101,29 +101,40 @@ repos:
     rev: 6.1.0
     hooks:
     -   id: flake8
-- repo: https://github.com/PyCQA/pylint
-  rev: v3.0.0a7
-  hooks:
-    - id: pylint
-      name: pylint
-      entry: pylint
-      language: system
-      types: [python]
-      files: ^src/
-      args:
-        [
-          '--output-format=parseable',
-          '--rcfile=pylintrc',
-        ]
-    - id: pylint
-      name: pylint-tests-directory
-      entry: pylint
-      language: system
-      types: [python]
-      files: ^tests/
-      args:
-        [
-          '--output-format=parseable',
-          '--disable=missing-class-docstring,missing-function-docstring,protected-access',
-          '--rcfile=pylintrc',
-        ]
+-   repo: https://github.com/pycqa/pydocstyle
+    rev: 6.3.0
+    hooks:
+    -   id: pydocstyle
+        files: ^src/
+    -   id: pydocstyle
+        files: ^tests/
+        args:
+          [
+            '--ignore=D103,D213',
+          ]
+-   repo: https://github.com/PyCQA/pylint
+    rev: v3.0.0a7
+    hooks:
+      - id: pylint
+        name: pylint
+        entry: pylint
+        language: system
+        types: [python]
+        files: ^src/
+        args:
+          [
+            '--output-format=parseable',
+            '--rcfile=pylintrc',
+          ]
+      - id: pylint
+        name: pylint-tests-directory
+        entry: pylint
+        language: system
+        types: [python]
+        files: ^tests/
+        args:
+          [
+            '--output-format=parseable',
+            '--disable=missing-class-docstring,missing-function-docstring,protected-access',
+            '--rcfile=pylintrc',
+          ]

src/pymovements/dataset/dataset.py

@@ -870,7 +870,6 @@ def path(self) -> Path:
 
         Example
         -------
-
         By passing a `str` or a `Path` as `path` during initialization you can explicitly set the
         directory path of the dataset:
         >>> import pymovements as pm

src/pymovements/dataset/dataset_definition.py

@@ -62,6 +62,7 @@ class DatasetDefinition:
     custom_read_kwargs : dict[str, Any], optional
         If specified, these keyword arguments will be passed to the file reading function.
     """
+
     # pylint: disable=too-many-instance-attributes
     name: str = '.'
 

src/pymovements/dataset/dataset_files.py

@@ -347,7 +347,6 @@ def add_fileinfo(
     pl.DataFrame:
         Dataframe with added columns from fileinfo dictionary keys.
     """
-
     df = df.select(
         [
             pl.lit(value).alias(column)

src/pymovements/dataset/dataset_paths.py

@@ -184,7 +184,6 @@ def dataset(self) -> Path:
 
         Example
         -------
-
         By passing a `str` or a `Path` as `path` during initialization you can explicitly set the
         directory path of the dataset:
         >>> import pymovements as pm
@@ -242,7 +241,6 @@ def events(self) -> Path:
 
         Example
         -------
-
         >>> import pymovements as pm
         >>>
         >>> dataset = pm.Dataset("ToyDataset", path='/path/to/your/dataset/')
@@ -273,7 +271,6 @@ def preprocessed(self) -> Path:
 
         Example
         -------
-
         >>> import pymovements as pm
         >>>
         >>> dataset = pm.Dataset("ToyDataset", path='/path/to/your/dataset/')
@@ -306,7 +303,6 @@ def raw(self) -> Path:
 
         Example
         -------
-
         >>> import pymovements as pm
         >>>
         >>> dataset = pm.Dataset("ToyDataset", path='/path/to/your/dataset/')

src/pymovements/datasets/gazebase.py

@@ -96,6 +96,7 @@ class GazeBase(DatasetDefinition):
 
     >>> dataset.load()# doctest: +SKIP
     """
+
     # pylint: disable=similarities
     # The PublicDatasetDefinition child classes potentially share code chunks for definitions.
 

src/pymovements/datasets/gazebasevr.py

@@ -97,6 +97,7 @@ class GazeBaseVR(DatasetDefinition):
 
     >>> dataset.load()# doctest: +SKIP
     """
+
     # pylint: disable=similarities
     # The PublicDatasetDefinition child classes potentially share code chunks for definitions.
 

src/pymovements/datasets/judo1000.py

@@ -89,6 +89,7 @@ class JuDo1000(DatasetDefinition):
 
     >>> dataset.load()# doctest: +SKIP
     """
+
     # pylint: disable=similarities
     # The PublicDatasetDefinition child classes potentially share code chunks for definitions.
 

src/pymovements/datasets/toy_dataset.py

@@ -87,6 +87,7 @@ class ToyDataset(DatasetDefinition):
 
     >>> dataset.load()# doctest: +SKIP
     """
+
     # pylint: disable=similarities
     # The PublicDatasetDefinition child classes potentially share code chunks for definitions.
 

src/pymovements/datasets/toy_dataset_eyelink.py

@@ -90,6 +90,7 @@ class ToyDatasetEyeLink(DatasetDefinition):
 
     >>> dataset.load()# doctest: +SKIP
     """
+
     # pylint: disable=similarities
     # The DatasetDefinition child classes potentially share code chunks for definitions.
 

src/pymovements/events/detection/_fill.py

@@ -17,9 +17,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-"""
-This module holds the implementation of the ivt algorithm.
-"""
+"""This module holds the implementation of the event fill function."""
 from __future__ import annotations
 
 import numpy as np
@@ -36,8 +34,7 @@ def fill(
         minimum_duration: int = 1,
         name: str = 'unclassified',
 ) -> EventDataFrame:
-    """
-    Classify all previously unclassified timesteps as events.
+    """Classify all previously unclassified timesteps as events.
 
     Parameters
     ----------
@@ -55,7 +52,6 @@ def fill(
     pl.DataFrame
         A dataframe with detected fixations as rows.
     """
-
     timesteps = np.array(timesteps)
 
     # Create binary mask where each existing event is marked.

src/pymovements/events/detection/_idt.py

@@ -17,9 +17,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-"""
-This module holds the implementation for idt algorithm.
-"""
+"""This module holds the implementation for I-DT algorithm."""
 from __future__ import annotations
 
 import numpy as np
@@ -60,8 +58,7 @@ def idt(
         include_nan: bool = False,
         name: str = 'fixation',
 ) -> EventDataFrame:
-    """
-    Fixation identification based on dispersion threshold.
+    """Fixation identification based on dispersion threshold (I-DT).
 
     The algorithm identifies fixations by grouping consecutive points
     within a maximum separation (dispersion) threshold and a minimum duration threshold.

src/pymovements/events/detection/_ivt.py

@@ -17,9 +17,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-"""
-This module holds the implementation of the ivt algorithm.
-"""
+"""This module holds the implementation of the I-VT algorithm."""
 from __future__ import annotations
 
 import numpy as np
@@ -41,8 +39,7 @@ def ivt(
         include_nan: bool = False,
         name: str = 'fixation',
 ) -> EventDataFrame:
-    """
-    Identification of fixations based on velocity-threshold
+    """Identification of fixations based on velocity-threshold (I-VT).
 
     The algorithm classifies each point as a fixation if the velocity is below
     the given velocity threshold. Consecutive fixation points are merged into

src/pymovements/events/detection/_library.py

@@ -17,9 +17,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-"""
-This module holds the EventDataFrame class.
-"""
+"""This module holds the EventDetectionLibrary class."""
 from __future__ import annotations
 
 from collections.abc import Callable
@@ -32,7 +30,7 @@ class EventDetectionLibrary:
 
     Attributes
     ----------
-    methods:
+    `methods`:
         Dictionary of event detection methods.
     """
 

src/pymovements/events/detection/_microsaccades.py

@@ -17,9 +17,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-"""
-This module holds the implementation for the Engbert microsaccades algorithm.
-"""
+"""This module holds the implementation for the Engbert microsaccades algorithm."""
 from __future__ import annotations
 
 from collections.abc import Sized

src/pymovements/events/frame.py

@@ -17,9 +17,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-"""
-This module holds the EventDataFrame class.
-"""
+"""This module holds the EventDataFrame class."""
 from __future__ import annotations
 
 from collections.abc import Sequence
@@ -126,9 +124,11 @@ def schema(self) -> pl.type_aliases.SchemaDict:
         return self.frame.schema
 
     def __len__(self) -> int:
+        """Get number of events in dataframe."""
         return self.frame.__len__()
 
     def __getitem__(self, *args: Any, **kwargs: Any) -> Any:
+        """Get item."""
         return self.frame.__getitem__(*args, **kwargs)
 
     @property
@@ -137,7 +137,7 @@ def columns(self) -> list[str]:
         return self.frame.columns
 
     def _add_duration_property(self) -> None:
-        """Adds duration property column to dataframe."""
+        """Add duration property column to dataframe."""
         self.frame = self.frame.select([pl.all(), duration().alias('duration')])
 
     def add_event_properties(

src/pymovements/events/properties.py

@@ -39,16 +39,16 @@ def amplitude(
         position_column: str = 'position',
         n_components: int = 2,
 ) -> pl.Expr:
-    """Amplitude of an event.
+    r"""Amplitude of an event.
 
     The amplitude is calculated as:
 
     .. math::
-        \\text{Amplitude} = \\sqrt{(x_{\\text{max}} - x_{\\text{min}})^2 +
-        (y_{\\text{max}} - y_{\\text{min}})^2}
+        \text{Amplitude} = \sqrt{(x_{\text{max}} - x_{\text{min}})^2 +
+        (y_{\text{max}} - y_{\text{min}})^2}
 
-    where :math:`(x_{\\text{min}},\\; x_{\\text{max}})` and
-    :math:`(y_{\\text{min}},\\; y_{\\text{max}})` are the minimum and maximum values of the
+    where :math:`(x_{\text{min}},\; x_{\text{max}})` and
+    :math:`(y_{\text{min}},\; y_{\text{max}})` are the minimum and maximum values of the
     :math:`x` and :math:`y` components of the gaze positions during an event.
 
     Parameters
@@ -80,16 +80,16 @@ def dispersion(
         position_column: str = 'position',
         n_components: int = 2,
 ) -> pl.Expr:
-    """
+    r"""
     Dispersion of an event.
 
     The dispersion is calculated as:
 
     .. math::
-        \\text{Dispersion} = x_{\\text{max}} - x_{\\text{min}} + y_{\\text{max}} - y_{\\text{min}}
+        \text{Dispersion} = x_{\text{max}} - x_{\text{min}} + y_{\text{max}} - y_{\text{min}}
 
-    where :math:`(x_{\\text{min}},\\; x_{\\text{max}})` and
-    :math:`(y_{\\text{min}},\\; y_{\\text{max}})` are the minimum and maximum values of the
+    where :math:`(x_{\text{min}},\; x_{\text{max}})` and
+    :math:`(y_{\text{min}},\; y_{\text{max}})` are the minimum and maximum values of the
     :math:`x` and :math:`y` components of the gaze positions during an event.
 
     Parameters
@@ -118,12 +118,12 @@ def disposition(
         position_column: str = 'position',
         n_components: int = 2,
 ) -> pl.Expr:
-    """Disposition of an event.
+    r"""Disposition of an event.
 
     The disposition is calculated as:
 
     .. math::
-        \\text{Disposition} = \\sqrt{(x_0 - x_n)^2 + (y_0 - y_n)^2}
+        \text{Disposition} = \sqrt{(x_0 - x_n)^2 + (y_0 - y_n)^2}
 
     where :math:`x_0` and :math:`y_0` are the coordinates of the starting position and
     :math:`x_n` and :math:`y_n` are the coordinates of the ending position of an event.
@@ -168,18 +168,18 @@ def location(
         position_column: str = 'position',
         n_components: int = 2,
 ) -> pl.Expr:
-    """Location of an event.
+    r"""Location of an event.
 
     For method ``mean`` the location is calculated as:
 
     .. math::
-        \\text{Location} = \\frac{1}{n} \\sum_{i=1}^n \\text{position}_i
+        \text{Location} = \frac{1}{n} \sum_{i=1}^n \text{position}_i
 
     For method ``median`` the location is calculated as:
 
     .. math::
-        \\text{Location} = \\text{median} \\left(\\text{position}_1, \\ldots,
-         \\text{position}_n \\right)
+        \text{Location} = \text{median} \left(\text{position}_1, \ldots,
+         \text{position}_n \right)
 
 
     Parameters
@@ -229,12 +229,12 @@ def peak_velocity(
         velocity_column: str = 'velocity',
         n_components: int = 2,
 ) -> pl.Expr:
-    """Peak velocity of an event.
+    r"""Peak velocity of an event.
 
     The peak velocity is calculated as:
 
     .. math::
-        \\text{Peak Velocity} = \\max \\left(\\sqrt{v_x^2 + v_y^2} \\right)
+        \text{Peak Velocity} = \max \left(\sqrt{v_x^2 + v_y^2} \right)
 
     where :math:`v_x` and :math:`v_y` are the velocity components in :math:`x` and :math:`y`
     direction, respectively.

src/pymovements/exceptions.py

@@ -25,5 +25,6 @@ class InvalidProperty(Exception):
     """Raised if requested property is invalid."""
 
     def __init__(self, property_name: str, valid_properties: list[str]):
+        """Initialize InvalidProperty object."""
         message = f"property '{property_name}' is invalid. Valid properties are: {valid_properties}"
         super().__init__(message)