ephys-link 2.0.0b6__py3-none-any.whl → 2.0.0b9__py3-none-any.whl

ephys_link/{util/base_bindings.py → utils/base_binding.py}

@@ -1,148 +1,176 @@
-"""Binding methods for Ephys Link manipulator platforms.
-
-Definition of the methods a platform binding class must implement to be used by Ephys Link.
-
-Usage: Implement the BaseBindings class when defining a platform binding to ensure it supports the necessary methods.
-"""
-
-from abc import ABC, abstractmethod
-
-from vbl_aquarium.models.unity import Vector3, Vector4
-
-
-class BaseBindings(ABC):
-    """Base class to enforce bindings manipulator platforms will support.
-
-    No need to catch exceptions as the Platform Handler will catch them.
-    """
-
-    @abstractmethod
-    async def get_manipulators(self) -> list[str]:
-        """Get a list of available manipulators on the current platform.
-
-        :returns: List of manipulator IDs.
-        :rtype: list[str]
-        """
-
-    @abstractmethod
-    async def get_axes_count(self) -> int:
-        """Get the number of axes for the current platform.
-
-        :returns: Number of axes.
-        :rtype: int
-        """
-
-    @abstractmethod
-    def get_dimensions(self) -> Vector4:
-        """Get the dimensions of the manipulators on the current platform (mm).
-
-        For 3-axis manipulators, copy the dimension of the axis parallel to the probe into w.
-
-        :returns: Dimensions of the manipulators.
-        :rtype: Vector4
-        """
-
-    @abstractmethod
-    async def get_position(self, manipulator_id: str) -> Vector4:
-        """Get the current position of a manipulator.
-
-        These will be the translation values of the manipulator (mm), so they may need to be rotated to unified space.
-        For 3-axis manipulators, copy the position of the axis parallel to the probe into w.
-
-        :param manipulator_id: Manipulator ID.
-        :type manipulator_id: str
-        :returns: Current position of the manipulator in platform space (mm).
-        :rtype: Vector4
-        """
-
-    @abstractmethod
-    async def get_angles(self, manipulator_id: str) -> Vector3:
-        """Get the current rotation angles of a manipulator in Yaw, Pitch, Roll (degrees).
-
-        :param manipulator_id: Manipulator ID.
-        :type manipulator_id: str
-        :returns: Current angles of the manipulator.
-        :rtype: Vector3
-        """
-
-    @abstractmethod
-    async def get_shank_count(self, manipulator_id: str) -> int:
-        """Get the number of shanks on a manipulator.
-
-        :param manipulator_id: Manipulator ID.
-        :type manipulator_id: str
-        :returns: Number of shanks on the manipulator.
-        :rtype: int
-        """
-
-    @abstractmethod
-    def get_movement_tolerance(self) -> float:
-        """Get the tolerance for how close the final position must be to the target position in a movement (mm).
-
-        :returns: Movement tolerance (mm).
-        :rtype: float
-        """
-
-    @abstractmethod
-    async def set_position(self, manipulator_id: str, position: Vector4, speed: float) -> Vector4:
-        """Set the position of a manipulator.
-
-        This will directly set the position in the original platform space.
-        For 3-axis manipulators, the first 3 values of the position will be used.
-
-        :param manipulator_id: Manipulator ID.
-        :type manipulator_id: str
-        :param position: Platform space position to set the manipulator to (mm).
-        :type position: Vector4
-        :param speed: Speed to move the manipulator to the position (mm/s).
-        :type speed: float
-        :returns: Final position of the manipulator in platform space (mm).
-        :rtype: Vector4
-        """
-
-    @abstractmethod
-    async def set_depth(self, manipulator_id: str, depth: float, speed: float) -> float:
-        """Set the depth of a manipulator.
-
-        This will directly set the depth stage in the original platform space.
-
-        :param manipulator_id: Manipulator ID.
-        :type manipulator_id: str
-        :param depth: Depth to set the manipulator to (mm).
-        :type depth: float
-        :param speed: Speed to move the manipulator to the depth (mm/s).
-        :type speed: float
-        :returns: Final depth of the manipulator in platform space (mm).
-        :rtype: float
-        """
-
-    @abstractmethod
-    async def stop(self, manipulator_id: str) -> None:
-        """Stop a manipulator."""
-
-    @abstractmethod
-    def platform_space_to_unified_space(self, platform_space: Vector4) -> Vector4:
-        """Convert platform space coordinates to unified space coordinates.
-
-        This is an axes-swapping transformation.
-
-        Unified coordinate space is the standard left-handed cartesian coordinate system
-        with an additional depth axis pointing from the base of the probe to the tip.
-
-        :param platform_space: Platform space coordinates.
-        :type platform_space: Vector4
-        :returns: Unified space coordinates.
-        :rtype: Vector4
-        """
-
-    @abstractmethod
-    def unified_space_to_platform_space(self, unified_space: Vector4) -> Vector4:
-        """Convert unified space coordinates to platform space coordinates.
-
-        This is an axes-swapping transformation.
-
-        :param unified_space: Unified space coordinates.
-        :type unified_space: Vector4
-        :returns: Platform space coordinates.
-        :rtype: Vector4
-        """
+"""Binding methods for Ephys Link manipulator platforms.
+
+Definition of the methods a platform binding class must implement to be used by Ephys Link.
+
+Usage:
+    Implement the BaseBindings class when defining a platform binding to ensure it supports the necessary methods.
+"""
+
+from abc import ABC, abstractmethod
+
+from vbl_aquarium.models.unity import Vector3, Vector4
+
+
+class BaseBinding(ABC):
+    """Base class to enforce bindings manipulator platforms will support.
+
+    No need to catch exceptions as the [Platform Handler][ephys_link.back_end.platform_handler] will catch them.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def get_display_name() -> str:
+        """Get the full display name of the platform.
+
+        Returns:
+            Full display name of the platform.
+        """
+
+    @staticmethod
+    @abstractmethod
+    def get_cli_name() -> str:
+        """Get the name of the platform for CLI usage.
+
+        This is the value used to identify the platform when using the `-t` flag in the CLI.
+
+        Returns:
+            Name of the platform to use on the CLI.
+        """
+
+    @abstractmethod
+    async def get_axes_count(self) -> int:
+        """Get the number of axes for the current platform.
+
+        Returns:
+            Number of axes.
+        """
+
+    @abstractmethod
+    def get_dimensions(self) -> Vector4:
+        """Get the dimensions of the manipulators on the current platform (mm).
+
+        For 3-axis manipulators, copy the dimension of the axis parallel to the probe into w.
+
+        Returns:
+            Dimensions of the manipulators.
+        """
+
+    @abstractmethod
+    async def get_manipulators(self) -> list[str]:
+        """Get a list of available manipulators on the current platform.
+
+        Returns:
+            List of manipulator IDs.
+        """
+
+    @abstractmethod
+    async def get_position(self, manipulator_id: str) -> Vector4:
+        """Get the current position of a manipulator.
+
+        These will be the translation values of the manipulator (mm), so they may need to be rotated to unified space.
+        For 3-axis manipulators, copy the position of the axis parallel to the probe into w.
+
+        Args:
+            manipulator_id: Manipulator ID.
+
+        Returns:
+            Current position of the manipulator in platform space (mm).
+        """
+
+    @abstractmethod
+    async def get_angles(self, manipulator_id: str) -> Vector3:
+        """Get the current rotation angles of a manipulator in Yaw, Pitch, Roll (degrees).
+
+        Args:
+            manipulator_id: Manipulator ID.
+
+        Returns:
+            Current angles of the manipulator.
+        """
+
+    @abstractmethod
+    async def get_shank_count(self, manipulator_id: str) -> int:
+        """Get the number of shanks on a manipulator.
+
+        Args:
+            manipulator_id: Manipulator ID.
+
+        Returns:
+            Number of shanks on the manipulator.
+        """
+
+    @abstractmethod
+    def get_movement_tolerance(self) -> float:
+        """Get the tolerance for how close the final position must be to the target position in a movement (mm).
+
+        Returns:
+            Movement tolerance (mm).
+        """
+
+    @abstractmethod
+    async def set_position(self, manipulator_id: str, position: Vector4, speed: float) -> Vector4:
+        """Set the position of a manipulator.
+
+        This will directly set the position in the original platform space.
+        For 3-axis manipulators, the first 3 values of the position will be used.
+
+        Args:
+            manipulator_id: Manipulator ID.
+            position: Platform space position to set the manipulator to (mm).
+            speed: Speed to move the manipulator to the position (mm/s).
+
+        Returns:
+            Final position of the manipulator in platform space (mm).
+        """
+
+    @abstractmethod
+    async def set_depth(self, manipulator_id: str, depth: float, speed: float) -> float:
+        """Set the depth of a manipulator.
+
+        This will directly set the depth stage in the original platform space.
+
+        Args:
+            manipulator_id: Manipulator ID.
+            depth: Depth to set the manipulator to (mm).
+            speed: Speed to move the manipulator to the depth (mm/s).
+
+        Returns:
+            Final depth of the manipulator in platform space (mm).
+        """
+
+    @abstractmethod
+    async def stop(self, manipulator_id: str) -> None:
+        """Stop a manipulator.
+
+        Args:
+            manipulator_id: Manipulator ID.
+        """
+
+    @abstractmethod
+    def platform_space_to_unified_space(self, platform_space: Vector4) -> Vector4:
+        """Convert platform space coordinates to unified space coordinates.
+
+        This is an axes-swapping transformation.
+
+        Unified coordinate space is the standard left-handed cartesian coordinate system
+        with an additional depth axis pointing from the base of the probe to the tip.
+
+        Args:
+            platform_space: Platform space coordinates.
+
+        Returns:
+            Unified space coordinates.
+        """
+
+    @abstractmethod
+    def unified_space_to_platform_space(self, unified_space: Vector4) -> Vector4:
+        """Convert unified space coordinates to platform space coordinates.
+
+        This is an axes-swapping transformation.
+
+        Args:
+            unified_space: Unified space coordinates.
+
+        Returns:
+            Platform space coordinates.
+        """

ephys_link/{util → utils}/console.py

@@ -1,130 +1,127 @@
-# ruff: noqa: T201
-"""Console class for printing messages to the console.
-
-Configure the console to print error and debug messages.
-
-Usage: Create a Console object and call the appropriate method to print messages.
-"""
-
-from logging import DEBUG, ERROR, INFO, basicConfig, getLogger
-
-from rich.logging import RichHandler
-from rich.traceback import install
-
-
-class Console:
-    def __init__(self, *, enable_debug: bool) -> None:
-        """Initialize console properties.
-
-        :param enable_debug: Enable debug mode.
-        :type enable_debug: bool
-        """
-        # Repeat message fields.
-        self._last_message = (0, "", "")
-        self._repeat_counter = 0
-
-        # Config logger.
-        basicConfig(
-            format="%(message)s",
-            datefmt="[%I:%M:%S %p]",
-            handlers=[RichHandler(rich_tracebacks=True, markup=True)],
-        )
-        self._log = getLogger("rich")
-        self._log.setLevel(DEBUG if enable_debug else INFO)
-
-        # Install Rich traceback.
-        install()
-
-    def debug_print(self, label: str, msg: str) -> None:
-        """Print a debug message to the console.
-
-        :param label: Label for the debug message.
-        :type label: str
-        :param msg: Debug message to print.
-        :type msg: str
-        """
-        self._repeatable_log(DEBUG, f"[b green]{label}", f"[green]{msg}")
-
-    def info_print(self, label: str, msg: str) -> None:
-        """Print info to console.
-
-        :param label: Label for the message.
-        :type label: str
-        :param msg: Message to print.
-        :type msg: str
-        """
-        self._repeatable_log(INFO, f"[b blue]{label}", msg)
-
-    def error_print(self, label: str, msg: str) -> None:
-        """Print an error message to the console.
-
-        :param label: Label for the error message.
-        :type label: str
-        :param msg: Error message to print.
-        :type msg: str
-        """
-        self._repeatable_log(ERROR, f"[b red]{label}", f"[red]{msg}")
-
-    def critical_print(self, msg: str) -> None:
-        """Print a critical message to the console.
-
-        :param msg: Critical message to print.
-        :type msg: str
-        """
-        self._log.critical(f"[b i red]{msg}")
-
-    @staticmethod
-    def pretty_exception(exception: Exception) -> str:
-        """Pretty print an exception.
-
-        :param exception: Exception to pretty print.
-        :type exception: Exception
-        :return: Pretty printed exception.
-        :rtype: str
-        """
-        return f"{type(exception).__name__}: {exception}"
-
-    def exception_error_print(self, label: str, exception: Exception) -> None:
-        """Print an error message with exception details to the console.
-
-        :param label: Label for the error message.
-        :type label: str
-        :param exception: Exception to print.
-        :type exception: Exception
-        """
-        self._log.exception(f"[b magenta]{label}:[/] [magenta]{Console.pretty_exception(exception)}")
-
-    # Helper methods.
-    def _repeatable_log(self, log_type: int, label: str, message: str) -> None:
-        """Add a row to the output table.
-
-        :param log_type: Type of log.
-        :type log_type: int
-        :param label: Label for the message.
-        :type label: str
-        :param message: Message.
-        :type message: str
-        """
-
-        # Compute if this is a repeated message.
-        message_set = (log_type, label, message)
-        if message_set == self._last_message:
-            # Handle repeat.
-            self._repeat_counter += 1
-
-            # Add an ellipsis row for first repeat.
-            if self._repeat_counter == 1:
-                self._log.log(log_type, "...")
-        else:
-            # Handle novel message.
-            if self._repeat_counter > 0:
-                # Complete previous repeat.
-                self._log.log(
-                    self._last_message[0],
-                    f"{self._last_message[1]}:[/] {self._last_message[2]}[/] x {self._repeat_counter}",
-                )
-                self._repeat_counter = 0
-
-            # Log new message.
-            self._log.log(log_type, f"{label}:[/] {message}")
-            self._last_message = message_set
+"""Console class for printing messages to the console.
+
+Configure the console to print error and debug messages.
+
+Usage:
+    Create a Console object and call the appropriate method to print messages.
+"""
+
+from logging import DEBUG, ERROR, INFO, basicConfig, getLogger
+from typing import final
+
+from rich.logging import RichHandler
+from rich.traceback import install
+
+
+@final
+class Console:
+    def __init__(self, *, enable_debug: bool) -> None:
+        """Initialize console properties.
+
+        Args:
+            enable_debug: Enable debug mode.
+        """
+        # Repeat message fields.
+        self._last_message = (0, "", "")
+        self._repeat_counter = 0
+
+        # Config logger.
+        basicConfig(
+            format="%(message)s",
+            datefmt="[%I:%M:%S %p]",
+            handlers=[RichHandler(rich_tracebacks=True, markup=True)],
+        )
+        self._log = getLogger("rich")
+        self._log.setLevel(DEBUG if enable_debug else INFO)
+
+        # Install Rich traceback.
+        _ = install()
+
+    def debug_print(self, label: str, msg: str) -> None:
+        """Print a debug message to the console.
+
+        Args:
+            label: Label for the debug message.
+            msg: Debug message to print.
+        """
+        self._repeatable_log(DEBUG, f"[b green]{label}", f"[green]{msg}")
+
+    def info_print(self, label: str, msg: str) -> None:
+        """Print info to console.
+
+        Args:
+            label: Label for the message.
+            msg: Message to print.
+        """
+        self._repeatable_log(INFO, f"[b blue]{label}", msg)
+
+    def error_print(self, label: str, msg: str) -> None:
+        """Print an error message to the console.
+
+        Args:
+            label: Label for the error message.
+            msg: Error message to print.
+        """
+        self._repeatable_log(ERROR, f"[b red]{label}", f"[red]{msg}")
+
+    def critical_print(self, msg: str) -> None:
+        """Print a critical message to the console.
+
+        Args:
+            msg: Critical message to print.
+        """
+        self._log.critical(f"[b i red]{msg}")
+
+    @staticmethod
+    def pretty_exception(exception: Exception) -> str:
+        """Pretty print an exception.
+
+        Args:
+            exception: Exception to pretty print.
+
+        Returns:
+            Pretty printed exception.
+        """
+        return f"{type(exception).__name__}: {exception}"
+
+    def exception_error_print(self, label: str, exception: Exception) -> None:
+        """Print an error message with exception details to the console.
+
+        Args:
+            label: Label for the error message.
+            exception: Exception to print.
+        """
+        self._log.exception(f"[b magenta]{label}:[/] [magenta]{Console.pretty_exception(exception)}")
+
+    # Helper methods.
+    def _repeatable_log(self, log_type: int, label: str, message: str) -> None:
+        """Add a row to the output table.
+
+        Args:
+            log_type: Type of log.
+            label: Label for the message.
+            message: Message.
+        """
+
+        # Compute if this is a repeated message.
+        message_set = (log_type, label, message)
+        if message_set == self._last_message:
+            # Handle repeat.
+            self._repeat_counter += 1
+
+            # Add an ellipsis row for first repeat.
+            if self._repeat_counter == 1:
+                self._log.log(log_type, "...")
+        else:
+            # Handle novel message.
+            if self._repeat_counter > 0:
+                # Complete previous repeat.
+                self._log.log(
+                    self._last_message[0],
+                    f"{self._last_message[1]}:[/] {self._last_message[2]}[/] x {self._repeat_counter}",
+                )
+                self._repeat_counter = 0
+
+            # Log new message.
+            self._log.log(log_type, f"{label}:[/] {message}")
+            self._last_message = message_set

ephys_link/utils/constants.py

@@ -0,0 +1,23 @@
+"""Globally accessible constants"""
+
+from os.path import abspath, dirname, join
+
+# Ephys Link ASCII.
+ASCII = r"""
+ ______       _                 _      _       _
+|  ____|     | |               | |    (_)     | |
+| |__   _ __ | |__  _   _ ___  | |     _ _ __ | | __
+|  __| | '_ \| '_ \| | | / __| | |    | | '_ \| |/ /
+| |____| |_) | | | | |_| \__ \ | |____| | | | |   <
+|______| .__/|_| |_|\__, |___/ |______|_|_| |_|_|\_\
+       | |           __/ |
+       |_|          |___/
+"""
+
+# Absolute path to the resource folder.
+PACKAGE_DIRECTORY = dirname(dirname(abspath(__file__)))
+RESOURCES_DIRECTORY = join(PACKAGE_DIRECTORY, "resources")
+BINDINGS_DIRECTORY = join(PACKAGE_DIRECTORY, "bindings")
+
+# Ephys Link Port
+PORT = 3000