Drop black in favor of ruff and generate stubs to expand docstrings i…

…n Pylance and IDEs (#137)

* update style workflows

* fix type-hint

* update dependencies and configuration

* add workflows to generate stubs

* improve _docs.py

* improve type-hints and ignore html templates

* fix stubs

* fix codespell

.github/workflows/publish.yaml

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

.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: pycrostates-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: pycrostates
 
-    - repo: https://github.com/psf/black-pre-commit-mirror
-      rev: 23.12.1
-      hooks:
-          - id: black
-            args: [--quiet]
-            files: pycrostates
-
     - repo: https://github.com/astral-sh/ruff-pre-commit
       rev: v0.1.9
       hooks:
           - id: ruff
-            args: [--fix, --exit-non-zero-on-fix]
+            name: ruff linter
+            args: [--fix]
+            files: pycrostates
+          - id: ruff-format
+            name: ruff formatter
             files: pycrostates
 
     - repo: https://github.com/codespell-project/codespell
       rev: v2.2.6
       hooks:
           - id: codespell
-            args: [--check-filenames, --ignore-words=.codespellignore, --skip=*.bib]
+            args: [--write-changes]
+            additional_dependencies: [tomli]
 
     - repo: https://github.com/pycqa/pydocstyle
       rev: 6.3.0

pycrostates/__init__.py

@@ -5,7 +5,7 @@
 from .utils._logs import set_log_level
 from .utils.sys_info import sys_info  # noqa: F401
 
-__all__ = (
+__all__: tuple[str, ...] = (
     "cluster",
     "datasets",
     "metrics",

pycrostates/cluster/__init__.py

@@ -18,7 +18,7 @@
 from .aahc import AAHCluster  # noqa: F401
 from .kmeans import ModKMeans  # noqa: F401
 
-__all__ = (
+__all__: tuple[str, ...] = (
     "ModKMeans",
     "AAHCluster",
 )

pycrostates/cluster/utils/__init__.py

@@ -2,4 +2,4 @@
 
 from .utils import optimize_order  # noqa: F401
 
-__all__ = ("optimize_order",)
+__all__: tuple[str, ...] = ("optimize_order",)

pycrostates/datasets/__init__.py

@@ -7,4 +7,4 @@
 
 from . import lemon
 
-__all__ = ("lemon",)
+__all__: tuple[str, ...] = ("lemon",)

pycrostates/io/__init__.py

@@ -4,4 +4,4 @@
 from .meas_info import ChInfo
 from .reader import read_cluster
 
-__all__ = ("ChData", "ChInfo", "read_cluster")
+__all__: tuple[str, ...] = ("ChData", "ChInfo", "read_cluster")

pycrostates/metrics/__init__.py

@@ -7,7 +7,7 @@
 from .dunn import dunn_score
 from .silhouette import silhouette_score
 
-__all__ = (
+__all__: tuple[str, ...] = (
     "calinski_harabasz_score",
     "davies_bouldin_score",
     "dunn_score",

pycrostates/preprocessing/__init__.py

@@ -7,4 +7,4 @@
 from .resample import resample
 from .spatial_filter import apply_spatial_filter
 
-__all__ = ("apply_spatial_filter", "extract_gfp_peaks", "resample")
+__all__: tuple[str, ...] = ("apply_spatial_filter", "extract_gfp_peaks", "resample")

pycrostates/segmentation/__init__.py

@@ -4,7 +4,7 @@
     compute_transition_matrix,
 )
 
-__all__ = (
+__all__: tuple[str, ...] = (
     "compute_expected_transition_matrix",
     "compute_transition_matrix",
     "EpochsSegmentation",

pycrostates/utils/__init__.py

@@ -3,4 +3,4 @@
 from ._config import get_config
 from .utils import _compare_infos, _corr_vectors, _distance_matrix  # noqa: F401
 
-__all__ = ("get_config",)
+__all__: tuple[str, ...] = ("get_config",)