Apply MNE philosophy to main class by returning self in methods modifying the instance in-place

doc/changes/latest.rst

@@ -22,7 +22,7 @@ Version 1.2
 Enhancements
 ------------
 
-- xxx
+- Apply MNE design philosophy by returning ``self`` in the methods modifying a :class:`~mne_lsl.stream.StreamLSL` and :class:`~mne_lsl.player.PlayerLSL` in-place (:pr:`200` by `Mathieu Scheltienne`_)
 
 Bugs
 ----

mne_lsl/player/_base.py

@@ -70,7 +70,7 @@ def anonymize(
         keep_his: bool = False,
         *,
         verbose: Optional[Union[bool, str, int]] = None,
-    ) -> None:
+    ) -> BasePlayer:
         """Anonymize the measurement information in-place.
 
         Parameters
@@ -79,6 +79,11 @@ def anonymize(
         %(keep_his_anonymize_info)s
         %(verbose)s
 
+        Returns
+        -------
+        player : instance of ``Player``
+            The player instance modified in-place.
+
         Notes
         -----
         %(anonymize_info_notes)s
@@ -91,6 +96,7 @@ def anonymize(
             stacklevel=1,
         )
         super().anonymize(daysback=daysback, keep_his=keep_his, verbose=verbose)
+        return self
 
     @fill_doc
     def get_channel_units(
@@ -130,7 +136,7 @@ def rename_channels(
         allow_duplicates: bool = False,
         *,
         verbose: Optional[Union[bool, str, int]] = None,
-    ) -> None:
+    ) -> BasePlayer:
         """Rename channels.
 
         Parameters
@@ -143,12 +149,17 @@ def rename_channels(
             If True (default False), allow duplicates, which will automatically be
             renamed with ``-N`` at the end.
         %(verbose)s
+
+        Returns
+        -------
+        player : instance of ``Player``
+            The player instance modified in-place.
         """
         self._check_not_started("rename_channels()")
         rename_channels(self.info, mapping, allow_duplicates)
 
     @abstractmethod
-    def start(self) -> None:  # pragma: no cover
+    def start(self) -> BasePlayer:  # pragma: no cover
         """Start streaming data."""
         pass
 
@@ -160,7 +171,7 @@ def set_channel_types(
         *,
         on_unit_change: str = "warn",
         verbose: Optional[Union[bool, str, int]] = None,
-    ) -> None:
+    ) -> BasePlayer:
         """Define the sensor type of channels.
 
         If the new channel type changes the unit type, e.g. from ``T/m`` to ``V``, the
@@ -179,15 +190,21 @@ def set_channel_types(
 
             .. versionadded:: MNE 1.4
         %(verbose)s
+
+        Returns
+        -------
+        player : instance of ``Player``
+            The player instance modified in-place.
         """
         self._check_not_started("set_channel_types()")
         super().set_channel_types(
             mapping=mapping, on_unit_change=on_unit_change, verbose=verbose
         )
         self._sinfo.set_channel_types(self.get_channel_types(unique=False))
+        return self
 
     @abstractmethod
-    def set_channel_units(self, mapping: dict[str, Union[str, int]]) -> None:
+    def set_channel_units(self, mapping: dict[str, Union[str, int]]) -> BasePlayer:
         """Define the channel unit multiplication factor.
 
         By convention, MNE stores data in SI units. But systems often stream in non-SI
@@ -207,6 +224,11 @@ def set_channel_units(self, mapping: dict[str, Union[str, int]]) -> None:
             The unit can be given as a human-readable string or as a unit multiplication
             factor, e.g. ``-6`` for microvolts corresponding to ``1e-6``.
 
+        Returns
+        -------
+        player : instance of ``Player``
+            The player instance modified in-place.
+
         Notes
         -----
         If the human-readable unit of your channel is not yet supported by MNE-LSL,
@@ -227,10 +249,11 @@ def set_channel_units(self, mapping: dict[str, Union[str, int]]) -> None:
             channel_wise=False,
             picks="all",
         )
+        return self
 
     def set_meas_date(
         self, meas_date: Optional[Union[datetime, float, tuple[float, float]]]
-    ) -> None:
+    ) -> BasePlayer:
         """Set the measurement start date.
 
         Parameters
@@ -243,6 +266,11 @@ def set_meas_date(
             object will be automatically created. If None, will remove
             the time reference.
 
+        Returns
+        -------
+        player : instance of ``Player``
+            The player instance modified in-place.
+
         See Also
         --------
         anonymize
@@ -255,9 +283,10 @@ def set_meas_date(
             stacklevel=1,
         )
         super().set_meas_date(meas_date)
+        return self
 
     @abstractmethod
-    def stop(self) -> None:
+    def stop(self) -> BasePlayer:
         """Stop streaming data on the mock real-time stream."""
         if self._streaming_thread is None:
             raise RuntimeError(

mne_lsl/player/player_lsl.py

@@ -66,12 +66,19 @@ def rename_channels(
         allow_duplicates: bool = False,
         *,
         verbose: Optional[Union[bool, str, int]] = None,
-    ) -> None:
+    ) -> PlayerLSL:
         super().rename_channels(mapping, allow_duplicates)
         self._sinfo.set_channel_names(self.info["ch_names"])
+        return self
+
+    def start(self) -> PlayerLSL:
+        """Start streaming data on the LSL :class:`~mne_lsl.lsl.StreamOutlet`.
 
-    def start(self) -> None:
-        """Start streaming data on the LSL :class:`~mne_lsl.lsl.StreamOutlet`."""
+        Returns
+        -------
+        player : instance of :class:`~mne_lsl.player.PlayerLSL`
+            The player instance modified in-place.
+        """
         if self._streaming_thread is not None:
             logger.warning(
                 "%s: The player is already started. "
@@ -86,6 +93,7 @@ def start(self) -> None:
         self._target_timestamp = local_clock()
         self._streaming_thread.start()
         logger.debug("%s: Started streaming thread", self._name)
+        return self
 
     @copy_doc(BasePlayer.set_channel_types)
     def set_channel_types(
@@ -94,26 +102,35 @@ def set_channel_types(
         *,
         on_unit_change: str = "warn",
         verbose: Optional[Union[bool, str, int]] = None,
-    ) -> None:
+    ) -> PlayerLSL:
         super().set_channel_types(
             mapping, on_unit_change=on_unit_change, verbose=verbose
         )
         self._sinfo.set_channel_types(self.get_channel_types(unique=False))
+        return self
 
     @copy_doc(BasePlayer.set_channel_units)
-    def set_channel_units(self, mapping: dict[str, Union[str, int]]) -> None:
+    def set_channel_units(self, mapping: dict[str, Union[str, int]]) -> PlayerLSL:
         super().set_channel_units(mapping)
         ch_units_after = np.array(
             [ch["unit_mul"] for ch in self.info["chs"]], dtype=np.int8
         )
         self._sinfo.set_channel_units(ch_units_after)
+        return self
+
+    def stop(self) -> PlayerLSL:
+        """Stop streaming data on the LSL :class:`~mne_lsl.lsl.StreamOutlet`.
 
-    def stop(self) -> None:
-        """Stop streaming data on the LSL :class:`~mne_lsl.lsl.StreamOutlet`."""
+        Returns
+        -------
+        player : instance of :class:`~mne_lsl.player.PlayerLSL`
+            The player instance modified in-place.
+        """
         logger.debug("%s: Stopping", self._name)
         super().stop()
         self._outlet = None
         self._reset_variables()
+        return self
 
     @copy_doc(BasePlayer._stream)
     def _stream(self) -> None: