Merge remote-tracking branch 'origin/main' into test_edfapi_not_insta…

…lled

I had to resolve the new directory structure on main ( src/eyelinkio ) with my renaming of modules in this PR (i.e. eyelinkio/read.py )

.circleci/config.yml

@@ -1,7 +1,11 @@
 version: 2.1
 
+
+orbs:
+  win: circleci/windows@4.1.1 # The Windows orb gives you everything you need to start using the Windows executor
+
 jobs:
-  test:
+  Test-Installed-SDK:
     docker:
       - image: circleci/python:3.10
 
@@ -21,12 +25,54 @@ jobs:
             sudo ldconfig
             python -m pip install --upgrade pip
             pip install -e ".[dev]"
+      - run:
+          name: Set environment variables
+          command: |
+            export EYELINKIO_USE_INSTALLED_EDFAPI=true
 
       - run:
           name: Run tests
           command: |
             pytest
   
+  test-macos:
+    macos:
+      xcode: 14.2.0
+    steps:
+      - checkout
+
+      - run:
+          name: Install dependencies
+          command: |
+            python -m pip install --upgrade pip
+            pip install -e ".[dev]"
+      - run:
+          name: Set environment variables
+          command: |
+            export EYELINKIO_USE_INSTALLED_EDFAPI=false
+      - run:
+          name: Run tests
+          command: |
+            pytest
+
+  test-windows:
+    executor: win/server-2022
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: |
+            python -m pip install --upgrade pip
+            pip install -e ".[dev]"
+      - run:
+          name: Set environment variables
+          command: |
+            set EYELINKIO_USE_INSTALLED_EDFAPI=false
+      - run:
+          name: Run tests
+          command: |
+            pytest
+
   build-docs:
     docker:
       - image: circleci/python:3.10
@@ -35,14 +81,6 @@ jobs:
       - run:
           name: Install dependencies
           command: |
-            sudo apt-get update
-            sudo apt install software-properties-common
-            sudo apt-get update
-            sudo add-apt-repository "deb http://download.sr-support.com/software SRResearch main"
-            wget -O - "http://download.sr-support.com/software/SRResearch_key" | sudo apt-key add -
-            sudo apt-get update
-            sudo apt-get install eyelink-edfapi
-            sudo ldconfig
             python -m pip install --upgrade pip
             pip install -e ".[dev]"
       - run:
@@ -79,11 +117,13 @@ workflows:
   version: 2
   test:
     jobs:
-      - test
+      - Test-Installed-SDK
       - build-docs
+      - test-macos
+      - test-windows
       - docs-deploy:
           requires:
-            - test
+            - Test-Installed-SDK
             - build-docs
           filters:
             branches:

.github/workflows/tests.yaml → .github/workflows/lint.yaml

@@ -21,4 +21,4 @@ jobs:
         with:
           python-version: '3.11'
       - run: pip install -e ".[dev]"
-      - run: ruff check eyelinkio
+      - run: ruff check src/eyelinkio

.github/workflows/test.yaml

@@ -0,0 +1,42 @@
+name: Run Tests (No SDK)
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest  # Latest Apple Silicon macOS
+          - macos-13  # Latest Intel-based macOS
+          - windows-latest
+        python-version: ['3.10']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -e ".[dev]"
+    
+    - name: Set environment variables On macOS and Linux
+      if: runner.os != 'Windows'
+      run: |
+        export EYELINKIO_USE_INSTALLED_EDFAPI=false
+
+    - name: Run tests
+      run: pytest

.gitignore

@@ -8,6 +8,8 @@ __pycache__/
 
 # C extensions
 *.so
+# Except for the following files
+!libedfapi/linux/libedfapi.so
 
 # Distribution / packaging
 .Python

LICENSE

@@ -1,3 +1,5 @@
+This license applies only to the code in `src/eyelinkio`. Files, code, and assets in `src/libedfapi` are explicitly excluded. All Files, code, and assets in `src/libedfapi` belong to SR Research Ltd. Copyright (c) 1996-2023, All Rights Reserved. 
+
 BSD 3-Clause License
 
 Copyright (c) 2024, Scott Huberty

MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include src *
+recursive-exclude tests *

README.md

@@ -1,20 +1,32 @@
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/scott-huberty/eyelinkio/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/scott-huberty/eyelinkio/tree/main)
+[![PyPI version](https://badge.fury.io/py/eyelinkio.svg)](https://badge.fury.io/py/eyelinkio)
+[![PyPI Download count](https://static.pepy.tech/badge/eyelinkio)](https://pepy.tech/project/eyelinkio)
+
 # EyeLinkIO 👀
 
 A lightweight library to import SR Research EDF files into Python.
 
-**This Software is currenly pre-alpha, meaning it is currently being developed**: Changes to the API (function names, etc.) may occur without warning. This library has been tested with MacOS and Linux, but not Windows.
+**This Software is currenly pre-alpha, meaning it is currently being developed**: Changes to the API (function names, etc.) may occur without warning.
 
 ## About the Eyelink Data Format
 
-The EyeLink Data Format (EDF; not to be confused with the [European Data Format](<https://www.edfplus.info>)) is used for storing eyetracking data from EyeLink eyetrackers. It was put forward by the company [SR Research](<https://www.sr-research.com>). SR Research EDF files store data in a binary format, and reading these files currently requires the ``eyelink-edfapi`` C library that is included in the EyeLink Software Development Kit.
+The EyeLink Data Format (EDF; not to be confused with the
+[European Data Format](<https://www.edfplus.info>)) is used for storing eyetracking data
+from EyeLink eyetrackers. It was put forward by the company
+[SR Research](<https://www.sr-research.com>). SR Research EDF files store data in a
+binary format, and reading these files requires interfacing with ``eyelink-edfapi`` C
+library that is typically included in the EyeLink Software Development Kit. EyeLinkIO
+Includes the necessary binaries to read EDF files, but can also be configured to use the
+EDF API library that is installed on your computer.
 
 ## Dependencies
 
 Strictly speaking, EyeLinkIO only requires Numpy. For converting data to pandas ``DataFrames`` or MNE-Python ``Raw`` instances, you must have those respective packages installed.
 
-> [!IMPORTANT]
-> - You must have the [EyeLink Software Development Kit](<https://www.sr-research.com/support/forum-3.html>) installed on your computer
-> - You must register an account on the forum to access the download (registration is free)
+> [!NOTE]
+>
+> - EyeLinkIO includes the Eyelink EDF API binary files that are needed to read EDF files.
+> - [See](#using-the-eyelink-developers-kit-edf-api-to-read-edf-files) If you want to use the EyeLink Developers Kit's EDF API library that is installed on your computer.
 
 ## Installation
 
@@ -39,9 +51,11 @@ pip install -e ./eyelinkio
 ```
 
 > [!IMPORTANT]  
+> To use the editable installation, you should:
+>
 >- Fork the repository on GitHub first.
 >- Clone your forked repository to your local machine.
->- Make sure you're in the directory *containing* the cloned `eyelinkio` folder when you run the command above
+>- Make sure you're in the directory *containing* the cloned `eyelinkio` folder when you run the command provided above
 
 This package is not currently available on Conda.
 
@@ -108,6 +122,30 @@ raw, calibration = edf_file.to_mne()
 
 See the [documentation](https://scott-huberty.github.io/eyelinkio/) for more.
 
+#### Using The EyeLink Developers Kit (EDF API) to read EDF files
+
+EyeLinkIO includes the Eyelink EDF API binary files that are needed to read EDF files,
+and by default it will rely on these files when reading reading your EDF files. However,
+if you have the
+[Eyelink Developers Kit](https://www.sr-research.com/support/forum-9.html)
+installed on your computer, you can explicitly direct
+EyeLinkIO to rely on the EDF API library that is included in the EyeLink Developers Kit,
+by setting the environment variable `EYELINKIO_USE_INSTALLED_EDFAPI` to `true` *before*
+importing the package:
+
+```python
+import os
+os.environ["EYELINKIO_USE_INSTALLED_EDFAPI"] = "true"
+
+import eyelinkio
+edf = eyelinkio.read_edf("path/to/edf/file")
+```
+
+> [!NOTE]
+>
+> - First download the [EyeLink Software Development Kit](<https://www.sr-research.com/support/forum-3.html>)
+> - You must register an account on the forum to access the download (registration is free)
+
 ## Acknowledgements
 
 This package was originally adapted from the [pyeparse](<https://github.com/pyeparse/pyeparse>) package (created by several of the core developers of [MNE-Python](<https://mne.tools/dev/index.html>)). It copies much of the EDF (Eyelink Data Format) reading code.

docs/changes/devel.rst

@@ -1,15 +1,33 @@
 .. _Scott Huberty: https://github.com/scott-huberty
 .. _Thinh Nguyen: https://github.com/ttngu207
+.. _Will Foran: https://github.com/WillForan
+
+
+0.3 (2024-12-12) 📦
+===================
+
+Bugfixes 🐞
+-----------
+
+- Improved error message handling in the case that the EyeLink EDF API is not available. By `Will Foran`_ (`#11 <https://github.com/scott-huberty/eyelinkio/pull/11>`__)
+
+
+New features 🚀
+---------------
+
+- You can now load EDF files without needing to install the EyeLink Developers Kit. By `Scott Huberty`_ (`#14 <https://github.com/scott-huberty/eyelinkio/pull/14>`__)
+- Added Continuous Integration (CI) testing for Windows and MacOS. By `Scott Huberty`_  (`#14 <https://github.com/scott-huberty/eyelinkio/pull/14>`__)
+
 
 0.2.0 (2024-08-01) 📦
 =====================
 
 New features 🚀
 ---------------
 
-- Added support for reading binocular data by `Scott Huberty`_ and `Thinh Nguyen`_. (`#5 <https://github.com/scott-huberty/eyelinkio/pulls/5>`__)
+- Added support for reading binocular data by `Scott Huberty`_ and `Thinh Nguyen`_. (`#5 <https://github.com/scott-huberty/eyelinkio/pull/5>`__)
 
-- Setup a changelog, using `towncrier <https://towncrier.readthedocs.io/en/stable/index.html>`_. by `Scott Huberty`_ (`#6 <https://github.com/scott-huberty/eyelinkio/pulls/6>`__)
+- Setup a changelog, using `towncrier <https://towncrier.readthedocs.io/en/stable/index.html>`_. by `Scott Huberty`_ (`#6 <https://github.com/scott-huberty/eyelinkio/pull/6>`__)
 
 
 Bugfixes 🐞

docs/contributing.rst

@@ -31,7 +31,7 @@ following command from the root of the package:
 
 .. code-block:: bash
 
-    $ ruff check eyelinkio
+    $ ruff check src/eyelinkio
 
 To build the docs:
 

docs/index.rst

@@ -5,8 +5,7 @@ A lightweight library to import SR Research EDF files into Python.
 
 .. important::
    **This Software is pre-alpha, meaning it is currently being developed**: Changes to the
-   API (function names, etc.) may occur without warning. This library has been tested with
-   MacOS and Linux, but not Windows.
+   API (function names, etc.) may occur without warning.
 
 About the EyeLink Data Format
 =============================
@@ -15,8 +14,10 @@ The EyeLink Data Format (EDF; not to be confused with the
 `European Data Format <https://www.edfplus.info>`_) is used for storing eyetracking data
 from EyeLink eyetrackers. It was put forward by the company
 `SR Research <https://www.sr-research.com>`_. SR Research EDF files store data in a
-binary format, and reading these files currently requires the `eyelink-edfapi` C
-library that is included in the Eyelink Software Developers Kit.
+binary format, and reading these files currently relies on the `eyelink-edfapi` C
+library that is included in the Eyelink Developers Kit. EyeLinkIO includes
+the binary files necessary to read EDF files, so the end-user does not need to install
+the Eyelink Software Developers Kit to use EyeLinkIO.
 
 Dependencies
 ============

docs/usage.rst

@@ -3,11 +3,6 @@
 User Guide
 ==========
 
-.. important::
-   - You must have the `EyeLink Software Development Kit <https://www.sr-research.com/support/forum-3.html>`_ installed on your computer
-   - You must register an account on the forum to access the download (registration is free)
-
-
 Installation
 ------------
 
@@ -44,9 +39,12 @@ For contributors to EyeLinkIO:
    pip install --editable ./eyelinkio
 
 .. important::
+
+   To install the package in editable mode, you must:
+
    - Fork the repository on GitHub first.
    - Clone your forked repository to your computer.
-   - Make sure you're in the directory *containing* the cloned ``eyelinkio`` folder when you run the command above.
+   - Make sure you're in the directory *containing* the cloned ``eyelinkio`` folder when you run the command provided above.
 
 Example Usage
 -------------
@@ -133,4 +131,31 @@ You can convert an instance of EDF to a pandas DataFrame or an MNE Raw instance
 
 .. seealso::
 
-   `Working with eyetracking data in MNE <https://mne.tools/stable/auto_tutorials/preprocessing/90_eyetracking_data.html>`_
+   `Working with eyetracking data in MNE <https://mne.tools/stable/auto_tutorials/preprocessing/90_eyetracking_data.html>`_
+
+
+Using the EDF API Library installed on your system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have the EDF API Library installed on your system, you can explicitly direct
+EyeLinkIO to rely on it when reading your EDF files. This can be done by setting the
+``EYELINKIO_USE_INSTALLED_EDFAPI`` parameter to ``true`` before importing EyeLinkIO.
+
+.. code:: python
+
+   import os
+   os.environ["EYELINKIO_USE_INSTALLED_EDFAPI"] = "true"
+
+   from eyelinkio.io import read_edf
+
+   fname = _get_test_fnames()[0]  # Replace this function with the path to your EDF file
+   edf_file = read_edf(fname)
+   print(edf_file)
+
+Otherwise, EyeLinkIO will rely on the EDF API Library that comes with the package.
+
+.. note::
+
+   If you want to install the EyeLink Developers Kit, you can download it from the
+   `SR Research website <https://www.sr-research.com/support/forum-3.html>`_. You will
+   need to register an account to access the download page (registration is free).