Improve type-hints and add stubs to expand docstrings (#194)

.github/workflows/doc.yaml

@@ -10,7 +10,7 @@ on:  # yamllint disable-line rule:truthy
 
 jobs:
   build:
-    timeout-minutes: 10
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -36,7 +36,11 @@ jobs:
       - name: Display system information
         run: mne_lsl-sys_info --developer
       - name: Build doc
-        run: make -C doc html
+        uses: nick-fields/retry@v2
+        with:
+          timeout_minutes: 10
+          max_attempts: 3
+          command: make -C doc html
       - name: Prune sphinx environment
         run: rm -R ./doc/_build/html/.doctrees
       - name: Upload documentation

.github/workflows/publish.yaml

@@ -23,9 +23,11 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools wheel
-          python -m pip install --progress-bar off .[build]
+          python -m pip install --progress-bar off -e .[build,stubs]
       - name: Display system information
         run: mne_lsl-sys_info --developer
+      - name: Generate stub files
+        run: python tools/stubgen.py
       - name: Build and publish
         env:
           TWINE_USERNAME: __token__

.github/workflows/pytest.yaml

@@ -54,7 +54,11 @@ jobs:
       - name: Display system information
         run: mne_lsl-sys_info --developer
       - name: Run pytest
-        run: pytest mne_lsl --cov=mne_lsl --cov-report=xml --cov-config=pyproject.toml -s
+        uses: nick-fields/retry@v2
+        with:
+          timeout_minutes: 10
+          max_attempts: 3
+          command: pytest mne_lsl --cov=mne_lsl --cov-report=xml --cov-config=pyproject.toml -s
       - name: Upload to codecov
         uses: codecov/codecov-action@v3
         with:
@@ -98,7 +102,11 @@ jobs:
       - name: Display system information
         run: mne_lsl-sys_info --developer
       - name: Run pytest
-        run: pytest mne_lsl --cov=mne_lsl --cov-report=xml --cov-config=pyproject.toml
+        uses: nick-fields/retry@v2
+        with:
+          timeout_minutes: 10
+          max_attempts: 3
+          command: pytest mne_lsl --cov=mne_lsl --cov-report=xml --cov-config=pyproject.toml
       - name: Upload to codecov
         uses: codecov/codecov-action@v3
         with:

.github/workflows/stubs.yaml

@@ -0,0 +1,41 @@
+name: stubs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+on:  # yamllint disable-line rule:truthy
+  schedule:
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+
+jobs:
+  generate:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Python 3.9
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9
+          architecture: 'x64'
+      - name: Install package
+        run: |
+          python -m pip install --progress-bar off --upgrade pip setuptools
+          python -m pip install --progress-bar off -e .[stubs]
+      - name: Display system information
+        run: mne_lsl-sys_info --developer
+      - name: Generate stub files
+        run: python tools/stubgen.py
+      - name: Push stub files
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          if [ -n "$(git status --porcelain)" ]; then
+            git add .
+            git commit -m "deploy stub files [ci skip]"
+            git push
+          fi

.pre-commit-config.yaml

@@ -1,32 +1,27 @@
-ci:
-    skip: [codespell, pydocstyle, yamllint]
-
 repos:
     - repo: https://github.com/pycqa/isort
       rev: 5.13.2
       hooks:
           - id: isort
             files: mne_lsl
 
-    - repo: https://github.com/psf/black-pre-commit-mirror
-      rev: 23.12.0
-      hooks:
-          - id: black
-            args: [--quiet]
-            files: mne_lsl
-
     - repo: https://github.com/astral-sh/ruff-pre-commit
       rev: v0.1.8
       hooks:
           - id: ruff
-            args: [--fix, --exit-non-zero-on-fix]
+            name: ruff linter
+            args: [--fix]
+            files: mne_lsl
+          - id: ruff-format
+            name: ruff formatter
             files: mne_lsl
 
     - repo: https://github.com/codespell-project/codespell
       rev: v2.2.6
       hooks:
           - id: codespell
-            args: [--check-filenames, --ignore-words=.codespellignore, --skip=*.svg]
+            args: [--write-changes]
+            additional_dependencies: [tomli]
 
     - repo: https://github.com/pycqa/pydocstyle
       rev: 6.3.0

README.md

@@ -1,3 +1,4 @@
+[![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)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
 [![codecov](https://codecov.io/gh/mne-tools/mne-lsl/graph/badge.svg?token=Xoeh6T13qi)](https://codecov.io/gh/mne-tools/mne-lsl)

mne_lsl/__init__.pyi

@@ -0,0 +1,5 @@
+from ._version import __version__ as __version__
+from .utils.config import sys_info as sys_info
+from .utils.logs import add_file_handler as add_file_handler
+from .utils.logs import logger as logger
+from .utils.logs import set_log_level as set_log_level

mne_lsl/_typing.pyi

@@ -0,0 +1,5 @@
+from numpy.typing import DTypeLike as DTypeLike
+
+ScalarFloatType: tuple[DTypeLike, ...]
+ScalarIntType: tuple[DTypeLike, ...]
+ScalarType: tuple[DTypeLike, ...]

mne_lsl/datasets/_fetch.pyi

@@ -0,0 +1,26 @@
+from pathlib import Path
+from typing import Union
+
+from ..utils._checks import ensure_path as ensure_path
+from ..utils._path import walk as walk
+from ..utils.logs import logger as logger
+
+def fetch_dataset(path: Path, base_url: str, registry: Union[str, Path]) -> Path:
+    """Fetch a dataset from the remote.
+
+    Parameters
+    ----------
+    path : str | Path
+        Local path where the dataset should be cloned.
+    base_url : str
+        Base URL for the remote data sources. All requests will be made relative to this
+        URL. If the URL does not end in a '/', a trailing '/' will be added
+        automatically.
+    registry : str | Path
+        Path to the txt file containing the registry.
+
+    Returns
+    -------
+    path : Path
+        Absolute path to the local clone of the dataset.
+    """

mne_lsl/datasets/sample.py

@@ -13,7 +13,7 @@
 if TYPE_CHECKING:
     from typing import Optional, Union
 
-_REGISTRY = files("mne_lsl.datasets") / "sample-registry.txt"
+_REGISTRY: Path = files("mne_lsl.datasets") / "sample-registry.txt"
 
 
 def _make_registry(

mne_lsl/datasets/sample.pyi

@@ -0,0 +1,29 @@
+from pathlib import Path
+from typing import Optional, Union
+
+from ..utils._checks import ensure_path as ensure_path
+from ._fetch import fetch_dataset as fetch_dataset
+
+_REGISTRY: Path
+
+def _make_registry(
+    folder: Union[str, Path], output: Optional[Union[str, Path]] = ...
+) -> None:
+    """Create the registry file for the sample dataset.
+
+    Parameters
+    ----------
+    folder : path-like
+        Path to the sample dataset.
+    output : path-like
+        Path to the output registry file.
+    """
+
+def data_path() -> Path:
+    """Return the path to the sample dataset, downloaded if needed.
+
+    Returns
+    -------
+    path : Path
+        Path to the sample dataset, by default in ``"~/mne_data/MNE-LSL"``.
+    """

mne_lsl/datasets/testing.py

@@ -13,7 +13,7 @@
 if TYPE_CHECKING:
     from typing import Optional, Union
 
-_REGISTRY = files("mne_lsl.datasets") / "testing-registry.txt"
+_REGISTRY: Path = files("mne_lsl.datasets") / "testing-registry.txt"
 
 
 def _make_registry(
@@ -25,7 +25,7 @@ def _make_registry(
     ----------
     folder : path-like
         Path to the sample dataset.
-    output : str | Path
+    output : path-like
         Path to the output registry file.
     """
     folder = ensure_path(folder, must_exist=True)

mne_lsl/datasets/testing.pyi

@@ -0,0 +1,29 @@
+from pathlib import Path
+from typing import Optional, Union
+
+from ..utils._checks import ensure_path as ensure_path
+from ._fetch import fetch_dataset as fetch_dataset
+
+_REGISTRY: Path
+
+def _make_registry(
+    folder: Union[str, Path], output: Optional[Union[str, Path]] = ...
+) -> None:
+    """Create the registry file for the sample dataset.
+
+    Parameters
+    ----------
+    folder : path-like
+        Path to the sample dataset.
+    output : path-like
+        Path to the output registry file.
+    """
+
+def data_path() -> Path:
+    """Return the path to the sample dataset, downloaded if needed.
+
+    Returns
+    -------
+    path : Path
+        Path to the sample dataset, by default in ``"~/mne_data/mne_lsl"``.
+    """

mne_lsl/lsl/__init__.pyi

@@ -0,0 +1,7 @@
+from .functions import library_version as library_version
+from .functions import local_clock as local_clock
+from .functions import protocol_version as protocol_version
+from .functions import resolve_streams as resolve_streams
+from .stream_info import StreamInfo as StreamInfo
+from .stream_inlet import StreamInlet as StreamInlet
+from .stream_outlet import StreamOutlet as StreamOutlet