ephys-link 1.3.3__py3-none-any.whl → 2.0.0__py3-none-any.whl

ephys_link/utils/console.py

@@ -0,0 +1,127 @@
+"""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

ephys_link/utils/converters.py

@@ -0,0 +1,86 @@
+"""Commonly used conversion functions."""
+
+from vbl_aquarium.models.unity import Vector4
+
+
+def scalar_mm_to_um(mm: float) -> float:
+    """Convert scalar values of millimeters to micrometers.
+
+    Args:
+        mm: Scalar value in millimeters.
+
+    Returns:
+        Scalar value in micrometers.
+    """
+    return mm * 1_000
+
+
+def vector_mm_to_um(mm: Vector4) -> Vector4:
+    """Convert vector values of millimeters to micrometers.
+
+    Args:
+        mm: Vector in millimeters.
+
+    Returns:
+        Vector in micrometers.
+    """
+    return mm * 1_000
+
+
+def um_to_mm(um: Vector4) -> Vector4:
+    """Convert micrometers to millimeters.
+
+    Args:
+        um: Length in micrometers.
+
+    Returns:
+        Length in millimeters.
+    """
+    return um / 1_000
+
+
+def vector4_to_array(vector4: Vector4) -> list[float]:
+    """Convert a [Vector4][vbl_aquarium.models.unity.Vector4] to a list of floats.
+
+    Args:
+        vector4: [Vector4][vbl_aquarium.models.unity.Vector4] to convert.
+
+    Returns:
+        List of floats.
+    """
+    return [vector4.x, vector4.y, vector4.z, vector4.w]
+
+
+def list_to_vector4(float_list: list[float | int]) -> Vector4:
+    """Convert a list of floats to a [Vector4][vbl_aquarium.models.unity.Vector4].
+
+    Args:
+        float_list: List of floats.
+
+    Returns:
+        First four elements of the list as a Vector4 padded with zeros if necessary.
+    """
+
+    def get_element(this_array: list[float | int], index: int) -> float:
+        """Safely get an element from an array.
+
+        Return 0 if the index is out of bounds.
+
+        Args:
+            this_array: Array to get the element from.
+            index: Index to get.
+
+        Returns:
+            Element at the index or 0 if the index is out of bounds.
+        """
+        try:
+            return this_array[index]
+        except IndexError:
+            return 0.0
+
+    return Vector4(
+        x=get_element(float_list, 0),
+        y=get_element(float_list, 1),
+        z=get_element(float_list, 2),
+        w=get_element(float_list, 3),
+    )

ephys_link/utils/startup.py

@@ -0,0 +1,65 @@
+"""Program startup helper functions."""
+
+from importlib import import_module
+from inspect import getmembers, isclass
+from pkgutil import iter_modules
+
+from packaging.version import parse
+from requests import ConnectionError, ConnectTimeout, get
+
+from ephys_link.__about__ import __version__
+from ephys_link.utils.base_binding import BaseBinding
+from ephys_link.utils.console import Console
+from ephys_link.utils.constants import ASCII, BINDINGS_DIRECTORY
+
+
+def preamble() -> None:
+    """Print the server startup preamble."""
+    print(ASCII)  # noqa: T201
+    print(__version__)  # noqa: T201
+    print()  # noqa: T201
+    print("This is the Ephys Link server window.")  # noqa: T201
+    print("You may safely leave it running in the background.")  # noqa: T201
+    print("To stop it, close this window or press CTRL + Pause/Break.")  # noqa: T201
+    print()  # noqa: T201
+
+
+def check_for_updates(console: Console) -> None:
+    """Check for updates to the Ephys Link.
+
+    Args:
+        console: Console instance for printing messages.
+    """
+    try:
+        response = get("https://api.github.com/repos/VirtualBrainLab/ephys-link/tags", timeout=10)
+        latest_version = str(response.json()[0]["name"])  # pyright: ignore [reportAny]
+        if parse(latest_version) > parse(__version__):
+            console.critical_print(f"Update available: {latest_version} (current: {__version__})")
+            console.critical_print("Download at: https://github.com/VirtualBrainLab/ephys-link/releases/latest")
+    except (ConnectionError, ConnectTimeout):
+        console.error_print(
+            "UPDATE", "Unable to check for updates. Ignore updates or use the the -i flag to disable checks.\n"
+        )
+
+
+def get_bindings() -> list[type[BaseBinding]]:
+    """Get all binding classes from the bindings directory.
+
+    Returns:
+        List of binding classes.
+    """
+    return [
+        binding_type
+        for module in iter_modules([BINDINGS_DIRECTORY])
+        for _, binding_type in getmembers(import_module(f"ephys_link.bindings.{module.name}"), isclass)
+        if issubclass(binding_type, BaseBinding) and binding_type != BaseBinding
+    ]
+
+
+def get_binding_display_to_cli_name() -> dict[str, str]:
+    """Get mapping of display to CLI option names of the available platform bindings.
+
+    Returns:
+        Dictionary of platform binding display name to CLI option name.
+    """
+    return {binding_type.get_display_name(): binding_type.get_cli_name() for binding_type in get_bindings()}

ephys_link-2.0.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: ephys-link
+Version: 2.0.0
+Summary: A Python Socket.IO server that allows any Socket.IO-compliant application to communicate with manipulators used in electrophysiology experiments.
+Project-URL: Documentation, https://virtualbrainlab.org/ephys_link/installation_and_use.html
+Project-URL: Issues, https://github.com/VirtualBrainLab/ephys-link/issues
+Project-URL: Source, https://github.com/VirtualBrainLab/ephys-link
+Author-email: Kenneth Yang <kjy5@uw.edu>
+Maintainer-email: Kenneth Yang <kjy5@uw.edu>
+License-Expression: GPL-3.0-only
+License-File: LICENSE
+Keywords: electrophysiology,ephys,manipulator,neuroscience,neurotech,new-scale,sensapex,socket-io,virtualbrainlab
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: <3.14,>=3.10
+Requires-Dist: aiohttp==3.11.12
+Requires-Dist: colorama==0.4.6
+Requires-Dist: keyboard==0.13.5
+Requires-Dist: packaging==24.2
+Requires-Dist: platformdirs==4.3.6
+Requires-Dist: pyserial==3.5
+Requires-Dist: python-socketio[asyncio-client]==5.12.1
+Requires-Dist: requests==2.32.3
+Requires-Dist: rich==13.9.4
+Requires-Dist: sensapex==1.400.3
+Requires-Dist: vbl-aquarium==1.0.0
+Description-Content-Type: text/markdown
+
+# Electrophysiology Manipulator Link
+
+[![PyPI version](https://badge.fury.io/py/ephys-link.svg)](https://badge.fury.io/py/ephys-link)
+[![Deploy Documentation](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/deploy-docs.yml)
+[![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://pydantic.dev)
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+<!-- [![Build](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/build.yml/badge.svg)](https://github.com/VirtualBrainLab/ephys-link/actions/workflows/build.yml) -->
+
+The [Electrophysiology Manipulator Link](https://github.com/VirtualBrainLab/ephys-link)
+(or Ephys Link for short) is a Python [Socket.IO](https://socket.io/docs/v4/#what-socketio-is) server that allows any
+Socket.IO-compliant application (such
+as [Pinpoint][Pinpoint])
+to communicate with manipulators used in electrophysiology experiments.
+
+<img width="100%" src="https://github.com/VirtualBrainLab/ephys-link/assets/82800265/0c7c60b1-0926-4697-a461-221554f82de1" alt="Manipulator and probe in pinpoint moving in sync">
+
+# Installation
+
+## Launch from Pinpoint (Recommended)
+
+Pinpoint comes bundled with the correct version of Ephys Link. If you are using Pinpoint on the same computer your
+manipulators are connected to, you can launch the server from within Pinpoint. Follow the instructions in
+the [Pinpoint documentation](https://virtualbrainlab.org/pinpoint/tutorials/tutorial_ephys_link.html#configure-and-launch-ephys-link).
+
+## Install as Standalone Executable
+
+1. Download the latest standalone executable or zip from
+   the [releases page](https://github.com/VirtualBrainLab/ephys-link/releases/latest).
+2. Double-click the executable file to start.
+
+# Documentation and More Information
+
+Complete documentation including how to add manipulators and API usage can be
+found on [Ephys Link's Documentation Website][docs].
+
+# Citing
+
+If this project is used as part of a research project you should cite
+the [Pinpoint repository](https://github.com/VirtualBrainLab/Pinpoint). Please email
+Dan ([dbirman@uw.edu](mailto:dbirman@uw.edu)) if you have questions.
+
+Please reach out to Kenneth ([kjy5@uw.edu](mailto:kjy5@uw.edu)) for questions
+about the Electrophysiology Manipulator Link server. Bugs may be reported
+through the issues tab.
+
+[Pinpoint]: https://github.com/VirtualBrainLab/Pinpoint
+
+[docs]: https://ephys-link.virtualbrainlab.org

ephys_link-2.0.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+ephys_link/__about__.py,sha256=HLJc82fZ6h65qdEwfCWx0U1_51VFQHVHv3kddt9t2Yk,23
+ephys_link/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ephys_link/__main__.py,sha256=sbFdC6KJjTfXDgRraU_fmGRPcF4I1Ur9PRDiD86dkRI,1449
+ephys_link/back_end/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ephys_link/back_end/platform_handler.py,sha256=PSlBa2_jM073uaF3MvCd-_a7XXEeTfn5KXJ7aPEwMVk,12149
+ephys_link/back_end/server.py,sha256=mb3K3pXSO-gHaSj1CGJ0v3CSOW5YCi-p0EOKoySRzKQ,10322
+ephys_link/bindings/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ephys_link/bindings/fake_binding.py,sha256=VCmKZha113kiHSmOZzKLfbaa8iXobefJFQPI3eCzuZE,2343
+ephys_link/bindings/mpm_binding.py,sha256=UdrWXiz16zJ7PSQBnYNtpTXs_1chbE_v1tvzeP7PrPk,10681
+ephys_link/bindings/ump_4_binding.py,sha256=zwAUo2wYBGq3NKa0zxdb5Jh_FMBAhf5yHdfKBP3m4dk,5407
+ephys_link/front_end/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ephys_link/front_end/cli.py,sha256=isIJs_sZbz7VbNvLgi-HyDlE-TyKD12auDhMTxAkWQU,3099
+ephys_link/front_end/gui.py,sha256=MDcrTS_Xz9bopAgamh4HknqRC10W8E6eOS3Kss_2ZKQ,6864
+ephys_link/resources/libum.dll,sha256=YaD4dwiSNohx-XxHjx2eQWPOBEVvUIXARvx37e_yqNw,316316
+ephys_link/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ephys_link/utils/base_binding.py,sha256=9ScaIXLwhAgHP4jLIG5LUf1AYjF_Jmf0nRH606_mXEQ,5399
+ephys_link/utils/console.py,sha256=52SYvXv_7Fx8QDL3RMFQoggQ1n5W93Yu5aU7uuJQgfg,3904
+ephys_link/utils/constants.py,sha256=10hiJfaWIrOmL-QLApimQMz2wQhViysB8KjOQZokwLQ,748
+ephys_link/utils/converters.py,sha256=ZdVmIX-LHCwM__F0SpjN_mfNGGetr1U97xvHd0hf8T0,2038
+ephys_link/utils/startup.py,sha256=W2_fMMYA90McKS9gPNWQO24NS6zp7aYWobunyMd5mC0,2565
+ephys_link-2.0.0.dist-info/METADATA,sha256=oEUdHYJA2luw0snpl44xK8iJx6kk6nG41t6ItJN6v7M,4835
+ephys_link-2.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ephys_link-2.0.0.dist-info/entry_points.txt,sha256=o8wV3AdnJ9o47vg9ymKxPNVq9pMdPq8UZHE_iyAJx-k,124
+ephys_link-2.0.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+ephys_link-2.0.0.dist-info/RECORD,,

{ephys_link-1.3.3.dist-info → ephys_link-2.0.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.24.2
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any