Move pylsl into the monorepo as a component

THIRD-PARTY-NOTICES.md

@@ -37,6 +37,36 @@ Catch2 (https://github.com/catchorg/Catch2), Boost Software License
 
 ---
 
+## pylsl (MIT License)
+
+Python binding, vendored as a component at `apps/pylsl/`. Retains its
+upstream MIT license, including the security integration added here; the notice
+is also kept at `apps/pylsl/LICENSE`.
+
+```
+Copyright (c) 2012-2018 Christian A. Kothe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+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.
+```
+
+---
+
 ## asio (Boost Software License 1.0)
 
 Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)

apps/pylsl/.gitignore

@@ -0,0 +1,21 @@
+/dist/
+/.idea/
+/src/pylsl.egg-info/
+/build/
+__pycache__
+*.so
+*.so.*
+*.pyc
+*.dll
+*.dylib
+*.cprof
+*.png
+/wheelhouse/
+/src/pylsl/include
+/src/pylsl/share
+.DS_Store
+
+uv.lock
+/src/pylsl/__version__.py
+/src/pylsl/lib/lslver.exe
+liblsl.zip

apps/pylsl/COMPONENT.md

@@ -0,0 +1,28 @@
+# pylsl component
+
+Security-enabled Python binding for Lab Streaming Layer, vendored into this
+monorepo as a component.
+
+## Licensing
+
+This component retains its upstream license (MIT, Copyright (c) 2012-2018
+Christian A. Kothe); see `LICENSE` in this directory. The security integration
+added here is contributed under that same MIT license. It consists of `ctypes`
+interface declarations and two stream properties that call the public liblsl C
+API, and contains no cryptographic implementation, so the proprietary Secure LSL
+terms do not apply to it. See COMPONENT LICENSING POLICY in the repository-root
+`LICENSE`.
+
+## Upstream tracking
+
+- Upstream: https://github.com/labstreaminglayer/pylsl
+- Based on upstream commit: `c90f623`
+- Security integration: interface declarations plus `StreamInfo.security_enabled`
+  and `StreamInfo.security_fingerprint`
+
+## Graceful degradation
+
+The security symbols are resolved inside `try`/`except AttributeError` and
+recorded in `_security_api_available` / `_stream_security_api_available`. Linked
+against a stock `liblsl` that does not export them, the binding imports and
+behaves exactly as upstream; the security properties simply report unavailable.

apps/pylsl/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012-2018 Christian A. Kothe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+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.

apps/pylsl/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+
+# If using Python 2.6 or less, then have to include package data, even though
+# it's already declared in setup.py
+include src/pylsl/lib/liblsl*.*
+include src/pylsl/lib/lsl*.*

apps/pylsl/README.md

@@ -0,0 +1,86 @@
+# pylsl
+
+![publish workflow](https://github.com/labstreaminglayer/pylsl/actions/workflows/publish-to-pypi.yml/badge.svg)
+[![PyPI version](https://badge.fury.io/py/pylsl.svg)](https://badge.fury.io/py/pylsl)
+
+This is the Python interface to the [Lab Streaming Layer (LSL)](https://github.com/sccn/labstreaminglayer).
+LSL is an overlay network for real-time exchange of time series between applications,
+most often used in research environments. LSL has clients for many other languages
+and platforms that are compatible with each other.
+
+Let us know if you encounter any bugs (ideally using the issue tracker on
+the GitHub project).
+
+# Installation
+
+## Prerequisites
+
+On all non-Windows platforms and for some Windows-Python combinations, you must first obtain a liblsl shared library. See the [liblsl repo documentation](https://github.com/sccn/liblsl) for further details.
+
+## Get pylsl from PyPI
+
+* `pip install pylsl`
+
+## Get pylsl from source
+
+This should only be necessary if you need to modify or debug pylsl.
+
+* Download the pylsl source: `git clone https://github.com/labstreaminglayer/pylsl.git && cd pylsl`
+* From the `pylsl` working directory, run `pip install .`.
+    * Note: You can use `pip install -e .` to install while keeping the files in-place. This is convenient for developing pylsl.
+
+# Usage
+
+See the examples in src/pylsl/examples. Note that these can be run directly from the commandline with (e.g.) `python -m pylsl.examples.{name-of-example}`.
+
+You can get a list of the examples with `python -c "import pylsl.examples; help(pylsl.examples)"`
+
+## liblsl loading
+
+`pylsl` will search for `liblsl` first at the filepath specified by an environment variable named `PYLSL_LIB`, then in the package directory (default location for Windows), then finally in normal system library folders.
+
+If the shared object is not installed onto a standard search path (or it is but can't be found for some [other bug](https://github.com/labstreaminglayer/pylsl/issues/48)), then we recommend that you copy it to the pylsl installed module path's `lib` subfolder. i.e. `{path/to/env/}site-packages/pylsl/lib`.
+
+* The `site-packages/pylsl` path will only exist _after_ you install `pylsl` in your Python environment.
+* You may have to create the `lib` subfolder.
+* Use `python -m site` to find the "site-packages" path.
+* Use `cp -L` on platforms that use symlinks.
+
+Alternatively, you can use an environment variable. Set the `PYLSL_LIB` environment variable to the location of the library or set `LD_LIBRARY_PATH` to the folder containing the library. For example,
+
+1. `PYLSL_LIB=/usr/local/lib/liblsl.so python -m pylsl.examples.{name-of-example}`, or
+2. `LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib python -m pylsl.examples.{name-of-example}`
+
+# For maintainers
+
+## Continuous Integration
+
+pylsl uses continuous integration and distribution. GitHub Actions will upload a new release to pypi whenever a Release is created in GitHub.
+Before creating the GitHub release, be sure to bump the version number in `pylsl/version.py` and consider updating the liblsl dependency
+in `.github/workflows/publish-to-pypi.yml`.
+
+### Linux Binaries Deprecated
+
+We recently stopped building binary wheels for Linux. In practice, the `manylinux` dependencies were often incompatible with real systems.
+
+## Manual Distribution
+
+1. Manual way:
+    1. `rm -Rf build dist *.egg-info`
+    1. `python setup.py sdist bdist_wheel`
+    1. Additional steps on Linux:
+        * `auditwheel repair dist/*.whl -w dist`
+        * `rm dist/*-linux_x86_64.whl`
+    1. `twine upload dist/*`
+1. For conda
+    1. build liblsl: `conda build ../liblsl/`
+    1. `conda build .`
+
+# Known Issues with Multithreading on Linux
+
+* At least for some versions of pylsl, it has been reported that running on Linux one cannot call ``pylsl`` functions from a thread that is not the main thread. This has been reported to cause access violations, and can occur during pulling from an inlet, and also from accessing an inlets info structure in a thread.
+* Recent tests with multithreading (especially when safeguarding library calls with locks) using Python 3.7.6. with pylsl 1.14 on Linux Mint 20 suggest that this issue is solved, or at least depends on your machine. See https://github.com/labstreaminglayer/pylsl/issues/29
+
+# Acknowledgments
+
+Pylsl was primarily written by Christian Kothe while at Swartz Center for Computational Neuroscience, UCSD. The LSL project was funded by the Army Research Laboratory under Cooperative Agreement Number W911NF-10-2-0022 as well as through NINDS grant 3R01NS047293-06S1. pylsl is maintained primarily by Chadwick Boulay. Thanks for contributions, bug reports, and suggestions go to Bastian Venthur, David Medine, Clemens Brunner, and Matthew Grivich.

apps/pylsl/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "pylsl"
+description = "Python library for importing XDF (Extensible Data Format)"
+authors = [
+  { name = "Christian Kothe", email = "christian.kothe@intheon.io" },
+  { name = "Chadwick Boulay", email = "chadwick.boulay@gmail.com" }
+]
+#license = {file = "LICENSE"}  # Bug in setuptools. https://github.com/astral-sh/uv/issues/9513
+readme = "README.md"
+requires-python = ">=3.9"
+dynamic = ["version"]
+keywords = [
+  "networking",
+  "LSL",
+  "Lab Streaming Layer",
+  "labstreaminglayer",
+  "data",
+  "acquisition",
+  "stream"
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Topic :: System :: Networking",
+  "Topic :: Scientific/Engineering",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "numpy>=1.21,<3",
+]
+
+[project.urls]
+Repository = "https://github.com/labstreaminglayer/pylsl"
+Issues = "https://github.com/labstreaminglayer/pylsl/issues"
+
+[project.optional-dependencies]
+examples = [
+    "pyqtgraph>=0.13.7",
+]
+#Changelog = "https://github.com/labstreaminglayer/pylsl/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "ruff>=0.8.2",
+]
+
+[build-system]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+license-files = []
+
+[tool.setuptools_scm]
+version_file = "src/pylsl/__version__.py"
+
+[tool.setuptools.package-data]
+pylsl = ["lib/*.dll"]

apps/pylsl/setup.py

@@ -0,0 +1,32 @@
+import sys
+
+from setuptools import setup
+# from setuptools.dist import Distribution
+
+
+# class BinaryDistribution(Distribution):
+#     """Distribution which always forces a binary package with platform name"""
+#     def has_ext_modules(foo):
+#         return sys.platform.startswith("win")
+
+try:
+    from wheel.bdist_wheel import bdist_wheel as _bdist_wheel
+
+    class bdist_wheel(_bdist_wheel):
+        def finalize_options(self):
+            super().finalize_options()
+            self.root_is_pure = not sys.platform.startswith("win")
+
+        def get_tag(self):
+            python, abi, plat = _bdist_wheel.get_tag(self)
+            # We don't contain any python source
+            python, abi = "py2.py3", "none"
+            return python, abi, plat
+except ImportError:
+    bdist_wheel = None
+
+
+setup(
+    # distclass=BinaryDistribution,
+    cmdclass={"bdist_wheel": bdist_wheel},
+)

apps/pylsl/src/pylsl/__init__.py

@@ -0,0 +1,48 @@
+"""Python API for the lab streaming layer.
+
+The lab streaming layer provides a set of functions to make instrument data
+accessible in real time within a lab network. From there, streams can be
+picked up by recording programs, viewing programs or custom experiment
+applications that access data streams in real time.
+
+The API covers two areas:
+- The "push API" allows to create stream outlets and to push data (regular
+  or irregular measurement time series, event data, coded audio/video frames,
+  etc.) into them.
+- The "pull API" allows to create stream inlets and read time-synched
+  experiment data from them (for recording, viewing or experiment control).
+
+"""
+
+from .__version__ import __version__ as __version__
+from .resolve import ContinuousResolver as ContinuousResolver
+from .resolve import resolve_streams as resolve_streams
+from .resolve import resolve_bypred as resolve_bypred
+from .resolve import resolve_byprop as resolve_byprop
+from .info import StreamInfo as StreamInfo
+from .inlet import StreamInlet as StreamInlet
+from .outlet import StreamOutlet as StreamOutlet
+from .util import IRREGULAR_RATE as IRREGULAR_RATE
+from .util import FOREVER as FOREVER
+from .util import proc_none as proc_none
+from .util import proc_clocksync as proc_clocksync
+from .util import proc_dejitter as proc_dejitter
+from .util import proc_monotonize as proc_monotonize
+from .util import proc_threadsafe as proc_threadsafe
+from .util import proc_ALL as proc_ALL
+from .util import protocol_version as protocol_version
+from .util import library_version as library_version
+from .util import library_info as library_info
+from .util import local_clock as local_clock
+from .util import is_secure_build as is_secure_build
+from .util import base_version as base_version
+from .util import security_version as security_version
+from .util import full_version as full_version
+from .util import check_security as check_security
+from .lib import cf_int8 as cf_int8
+from .lib import cf_int16 as cf_int16
+from .lib import cf_int32 as cf_int32
+from .lib import cf_int64 as cf_int64
+from .lib import cf_float32 as cf_float32
+from .lib import cf_double64 as cf_double64
+from .lib import cf_string as cf_string

apps/pylsl/src/pylsl/examples/GetTimeCorrection.py

@@ -0,0 +1,25 @@
+"""Example program to show how to read a multi-channel time series from LSL."""
+
+import time
+
+from pylsl import StreamInlet, resolve_byprop
+
+
+def main():
+    # first resolve an EEG stream on the lab network
+    print("looking for an EEG stream...")
+    streams = resolve_byprop("type", "EEG")
+    info = streams[0]
+
+    # create a new inlet to read from the stream
+    inlet = StreamInlet(info)
+
+    print("Connected to outlet " + info.name() + "@" + info.hostname())
+    while True:
+        offset = inlet.time_correction()
+        print("Offset: " + str(offset))
+        time.sleep(1)
+
+
+if __name__ == "__main__":
+    main()