napari-track-edit 1.0.0__tar.gz

napari_track_edit-1.0.0/.github/CODEOWNERS

@@ -0,0 +1,9 @@
+# Caroline is the default reviewer for all code
+* @cmalinmayor
+
+# Anniek is the tree widget expert
+/src/napari_track_edit/data_views/views/tree_view/* @anniekstok
+
+
+# Anniek is also the import/export expert
+/src/napari_track_edit/import_export/* @anniekstok

napari_track_edit-1.0.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      dependencies:
+        patterns:
+          - "*"

napari_track_edit-1.0.0/.github/workflows/benchmark-report.yml

@@ -0,0 +1,63 @@
+name: Benchmark
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  deployments: write
+  contents: write
+
+jobs:
+  benchmark:
+    name: Report benchmarks on gh-pages
+    runs-on: ubuntu-latest
+    env:
+      UV_NO_SYNC: "1"
+    steps:
+      - uses: actions/checkout@v7
+      # The Ubuntu runner image ships broken Microsoft apt repos whose signature
+      # is periodically invalid ("Clearsigned file isn't valid, got 'NOSPLIT'"),
+      # which fails the apt-get update inside setup-qt-libs. We don't need them.
+      - name: Remove broken Microsoft apt sources (ubuntu runner image)
+        run: |
+          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list \
+                     /etc/apt/sources.list.d/azure-cli.list \
+                     /etc/apt/sources.list.d/azure-cli.sources
+      - uses: tlambert03/setup-qt-libs@v1
+
+      # wgpu (via pygfx/fastplotlib, used by the tree view) needs a real Vulkan/GL
+      # adapter; Xvfb (below) only provides X11/GLX, not Vulkan. lavapipe/llvmpipe
+      # give it a software one, matching how pygfx/wgpu-py run their own Linux CI.
+      - name: Install llvmpipe and lavapipe for offscreen wgpu rendering
+        run: |
+          sudo apt-get update -y -qq
+          sudo apt-get install -y libegl1-mesa-dev libgl1-mesa-dri libxcb-xfixes0-dev mesa-vulkan-drivers
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --no-dev --group testing
+
+      # tests/benchmarks is ignored by default pytest config; `-o addopts=` clears
+      # that. GUI benchmarks need a real GL context, hence aganders3/headless-gui.
+      - name: Run benchmarks
+        uses: aganders3/headless-gui@v2
+        with:
+          run: uv run pytest tests/benchmarks -o addopts= --benchmark-json output.json
+
+      - name: Store benchmark results
+        uses: benchmark-action/github-action-benchmark@v1
+        with:
+          name: napari_track_edit benchmarks (pytest-benchmark)
+          tool: "pytest"
+          output-file-path: output.json
+          benchmark-data-dir-path: benchmarks
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: true

napari_track_edit-1.0.0/.github/workflows/benchmark_pr.py

@@ -0,0 +1,142 @@
+"""Compare two pytest-benchmark JSON files and produce a markdown table.
+
+Usage:
+    python benchmark_pr.py <old.json> <new.json> <output.md> [header]
+
+The table reports mean ± standard deviation for human readability, but the
+pass/fail gate compares the *median*. Median is robust to a single outlier round
+in either direction: `min` is biased down by an accidentally-fast run, `mean` up
+by an unlucky-slow one (a transient OS/GC spike). With >=3 rounds the median
+ignores one such spike, which is what keeps the noisy single-action benchmarks
+from tripping the gate spuriously.
+
+Exits with code 1 if any benchmark's median regresses by more than
+REGRESSION_THRESHOLD percent.
+"""
+
+import json
+import os
+import sys
+
+import pandas as pd
+
+REGRESSION_THRESHOLD = 50  # percent
+# Benchmarks with a median below this floor are dominated by timer resolution and OS
+# scheduling jitter rather than the code being measured, so a "regression" on them is
+# noise, not signal: skip the gate (still shown in the report) unless the benchmark is
+# slow on at least one side, which means it should have been caught by the floor already.
+NOISE_FLOOR_SECONDS = 0.02
+
+
+def load_stats(path):
+    with open(path) as f:
+        data = json.load(f)
+
+    commit = data["commit_info"]["id"]
+
+    rows = []
+    for d in data["benchmarks"]:
+        s = d["stats"]
+        rows.append(
+            {
+                "Benchmark": d["name"],
+                "median": s["median"],
+                "mean": s["mean"],
+                "stddev": s["stddev"],
+            }
+        )
+
+    return commit, pd.DataFrame(rows)
+
+
+def _fmt(mean, std):
+    return f"{mean:.5f} ± {std:.5f}"
+
+
+def _write(out_file, report):
+    with open(out_file, "w") as f:
+        f.write(report)
+    print(report)  # noqa: T201
+
+
+def make_report(old_path, new_path, out_file, header=None):
+    new_commit, new_df = load_stats(new_path)
+
+    # No baseline available (e.g. the first PR introducing benchmarks, or a run on
+    # a base commit that predates the suite). Report HEAD-only numbers and pass.
+    if not os.path.exists(old_path) or os.path.getsize(old_path) == 0:
+        df = pd.DataFrame(
+            {
+                "Benchmark": new_df["Benchmark"],
+                f"Median (s) HEAD {new_commit}": new_df["median"].map("{:.5f}".format),
+                f"Mean ± SD (s) HEAD {new_commit}": [
+                    _fmt(m, s)
+                    for m, s in zip(new_df["mean"], new_df["stddev"], strict=True)
+                ],
+            }
+        )
+        # disable_numparse: see note on the comparison table below.
+        report = df.to_markdown(index=False, disable_numparse=True)
+        note = "_No baseline found; showing HEAD results only (no comparison)._"
+        report = f"{note}\n\n{report}"
+        if header:
+            report = f"## {header}\n\n{report}"
+        _write(out_file, report)
+        return
+
+    old_commit, old_df = load_stats(old_path)
+
+    # Merge on benchmark name (drops benchmarks present on only one side).
+    merged = old_df.merge(new_df, on="Benchmark", suffixes=("_old", "_new"))
+
+    # Gate on the median (see module docstring).
+    pct_change = (
+        100 * (merged["median_new"] - merged["median_old"]) / merged["median_old"]
+    )
+
+    # A benchmark below the floor on both sides is dominated by timer resolution and OS
+    # scheduling jitter rather than the code being measured, so a "regression" on it is
+    # noise, not signal: exclude it from the gate (still shown in the report).
+    above_floor = (merged["median_old"] >= NOISE_FLOOR_SECONDS) | (
+        merged["median_new"] >= NOISE_FLOOR_SECONDS
+    )
+
+    # Median columns first: they drive the gate, so "Median Change" is verifiable
+    # straight from them. Mean ± SD follows as a noise indicator (a wide SD or a mean
+    # far from the median flags a spiky benchmark whose median we're rightly trusting).
+    df = pd.DataFrame(
+        {
+            "Benchmark": merged["Benchmark"],
+            f"Median (s) BASE {old_commit}": merged["median_old"].map("{:.5f}".format),
+            f"Median (s) HEAD {new_commit}": merged["median_new"].map("{:.5f}".format),
+            "Median Change": pct_change.map("{:+.2f}%".format),
+            f"Mean ± SD (s) BASE {old_commit}": [
+                _fmt(m, s)
+                for m, s in zip(merged["mean_old"], merged["stddev_old"], strict=True)
+            ],
+            f"Mean ± SD (s) HEAD {new_commit}": [
+                _fmt(m, s)
+                for m, s in zip(merged["mean_new"], merged["stddev_new"], strict=True)
+            ],
+        }
+    )
+
+    # disable_numparse: keep our fixed-precision strings exactly (tabulate otherwise
+    # re-parses numeric-looking cells and strips trailing zeros, so medians would show
+    # inconsistent precision next to the mean ± SD column).
+    report = df.to_markdown(index=False, disable_numparse=True)
+    if header:
+        report = f"## {header}\n\n{report}"
+    _write(out_file, report)
+
+    # Fail if any benchmark above the noise floor regressed beyond threshold
+    if (above_floor & (pct_change > REGRESSION_THRESHOLD)).any():
+        print(  # noqa: T201
+            f"\nFAILED: median regression exceeds {REGRESSION_THRESHOLD}% threshold"
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    header = sys.argv[4] if len(sys.argv) > 4 else None
+    make_report(sys.argv[1], sys.argv[2], sys.argv[3], header)

napari_track_edit-1.0.0/.github/workflows/benchmarks.yml

@@ -0,0 +1,141 @@
+name: benchmarks
+
+on:
+  pull_request: {}
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Needed for peter-evans/commit-comment to post the benchmark report on the commit.
+permissions:
+  contents: write
+
+jobs:
+  benchmark:
+    name: Benchmark (${{ matrix.platform }})
+    runs-on: ${{ matrix.platform }}
+    if: github.event_name == 'pull_request'
+    # Healthy runs finish in ~10 minutes; without this a hang (e.g. a wgpu/tree-widget
+    # deadlock) burns the full 360-minute default before GitHub cancels it.
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+    env:
+      # Stop `uv run` from auto-resyncing (which would drop the `testing` group).
+      # Each benchmark step below runs its own explicit `uv sync` after checkout so
+      # base and head are each measured against *their own* locked dependencies.
+      UV_NO_SYNC: "1"
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 50
+      # The Ubuntu runner image ships broken Microsoft apt repos whose signature
+      # is periodically invalid ("Clearsigned file isn't valid, got 'NOSPLIT'"),
+      # which fails the apt-get update inside setup-qt-libs. We don't need them.
+      - name: Remove broken Microsoft apt sources (ubuntu runner image)
+        if: runner.os == 'Linux'
+        run: |
+          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list \
+                     /etc/apt/sources.list.d/azure-cli.list \
+                     /etc/apt/sources.list.d/azure-cli.sources
+      - uses: tlambert03/setup-qt-libs@v1
+
+      # wgpu (via pygfx/fastplotlib, used by the tree view) needs a real Vulkan/GL
+      # adapter; Xvfb (below) only provides X11/GLX, not Vulkan. lavapipe/llvmpipe
+      # give it a software one, matching how pygfx/wgpu-py run their own Linux CI.
+      - name: Install llvmpipe and lavapipe for offscreen wgpu rendering
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update -y -qq
+          sudo apt-get install -y libegl1-mesa-dev libgl1-mesa-dri libxcb-xfixes0-dev mesa-vulkan-drivers
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Set Windows resolution
+        if: runner.os == 'Windows'
+        run: Set-DisplayResolution -Width 1920 -Height 1080 -Force
+        shell: powershell
+
+      - name: Install Windows OpenGL
+        if: runner.os == 'Windows'
+        run: |
+          git clone --depth 1 https://github.com/pyvista/gl-ci-helpers.git
+          powershell gl-ci-helpers/appveyor/install_opengl.ps1
+          if (Test-Path -Path "C:\Windows\system32\opengl32.dll" -PathType Leaf) {Exit 0} else {Exit 1}
+        shell: powershell
+
+      # Same-runner base-vs-head comparison (running baseline fresh every PR) turned
+      # out not to fix cross-run noise either -- swings as large as the ones it was
+      # meant to prevent still showed up within a single same-runner run. Since running
+      # baseline live buys no real stability, cache it per base-SHA instead: the first
+      # PR against a given base commit produces it, every later PR against that same
+      # base restores it instead of re-running -- half the benchmark cost with no
+      # measurement downside.
+      - name: Retrieve cached baseline if available
+        uses: actions/cache/restore@v5
+        id: cache_baseline
+        with:
+          path: baseline.json
+          key: benchmark-${{ matrix.platform }}-${{ github.event.pull_request.base.sha }}
+
+      # The benchmark suite lives under tests/benchmarks, which the default pytest
+      # config ignores; `-o addopts=` clears that so it is collected here. The GUI
+      # benchmarks need a real GL context, hence aganders3/headless-gui.
+      #
+      # Runs its own `uv sync` after checkout so base is measured against its OWN
+      # locked dependencies, not head's. This is what makes dependency-bump PRs
+      # (funtracks/tracksdata/...) measure the real base-vs-head delta: without this,
+      # base code would run against head's deps -- an apples-to-oranges comparison
+      # that reports fictional regressions whenever a dependency changes a shared
+      # contract. `git checkout -f` discards any uv.lock churn from a previous sync.
+      # Tolerant on purpose: the base commit may predate the benchmark suite, in which
+      # case there is no baseline and the report falls back to HEAD-only numbers.
+      - name: Run baseline benchmark if not in cache
+        if: steps.cache_baseline.outputs.cache-hit != 'true'
+        continue-on-error: true
+        uses: aganders3/headless-gui@v2
+        with:
+          run: |
+            git checkout -f ${{ github.event.pull_request.base.sha }}
+            uv sync --no-dev --group testing
+            uv run pytest tests/benchmarks -o addopts= --benchmark-json baseline.json
+
+      - name: Cache baseline results
+        uses: actions/cache/save@v5
+        if: steps.cache_baseline.outputs.cache-hit != 'true' && hashFiles('baseline.json') != ''
+        with:
+          path: baseline.json
+          key: benchmark-${{ matrix.platform }}-${{ github.event.pull_request.base.sha }}
+
+      - name: Run benchmark on PR head
+        uses: aganders3/headless-gui@v2
+        with:
+          run: |
+            git checkout -f ${{ github.event.pull_request.head.sha }}
+            uv sync --no-dev --group testing
+            uv run pytest tests/benchmarks -o addopts= --benchmark-json pr.json
+
+      - name: Generate report
+        id: report
+        run: |
+          uv run --with pandas --with tabulate python .github/workflows/benchmark_pr.py baseline.json pr.json report.md "Benchmark: ${{ matrix.platform }}"
+        continue-on-error: true
+
+      - name: Comment on commit with report
+        uses: peter-evans/commit-comment@v4
+        if: github.event.pull_request.head.repo.fork == false
+        with:
+          body-path: report.md
+
+      - name: Fail if regression detected
+        if: steps.report.outcome == 'failure'
+        run: exit 1

napari_track_edit-1.0.0/.github/workflows/deploy.yml

@@ -0,0 +1,35 @@
+name: Deploy
+
+on:
+  push:
+    tags: ["*"]
+  workflow_dispatch:
+
+jobs:
+  build-n-publish:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI
+    runs-on: ubuntu-latest
+    if: contains(github.ref, 'tags')
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.x"
+      - name: Build a binary wheel and a source tarball
+        run: |
+          python -m pip install -U pip
+          python -m pip install -U setuptools setuptools_scm build
+          python -m build --sdist --wheel --outdir dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+      - name: Create release
+        uses: softprops/action-gh-release@v3
+        with:
+          draft: ${{ contains(github.ref_name, '-dev') }}
+          prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-a') || contains(github.ref_name, '-b') }}
+          generate_release_notes: true

napari_track_edit-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Docs build
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python 3.11
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.11'
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync
+      - name: Build docs
+        run: |
+          cd docs/
+          uv run make html
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/build/html
+
+  # Deploy the artifact to GitHub pages.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

napari_track_edit-1.0.0/.github/workflows/download-sources.yml

@@ -0,0 +1,42 @@
+name: download sources
+
+# Checks that the example data the app downloads (Zenodo, Google Drive, CTC) is
+# still available. These servers are flaky, so the check is kept out of the normal
+# test run (see the `network` marker in pyproject.toml) and runs monthly instead.
+on:
+  schedule:
+    - cron: "0 6 1 * *" # 06:00 UTC on the 1st of every month
+  workflow_dispatch:
+
+jobs:
+  download-sources:
+    name: Download sources are reachable
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      # disable resyncing on uv run
+      UV_NO_SYNC: "1"
+    steps:
+      - uses: actions/checkout@v7
+      # The Ubuntu runner image ships broken Microsoft apt repos whose signature
+      # is periodically invalid, which fails the apt-get update inside setup-qt-libs.
+      - name: Remove broken Microsoft apt sources (ubuntu runner image)
+        run: |
+          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list \
+                     /etc/apt/sources.list.d/azure-cli.list \
+                     /etc/apt/sources.list.d/azure-cli.sources
+      - uses: tlambert03/setup-qt-libs@v1
+
+      - name: Set up Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --no-dev --group testing
+
+      - name: Test
+        uses: aganders3/headless-gui@v2
+        with:
+          run: uv run pytest --color=yes -m network tests

napari_track_edit-1.0.0/.github/workflows/make_bundle_app.yml

@@ -0,0 +1,17 @@
+name: bundleApp
+
+on:
+  release:
+    types:
+      - released
+      - published
+  # motile_tracker_bundle_app will be triggered when the release is changed from draft to published
+
+jobs:
+  packaging:
+    permissions:
+      contents: write
+    uses: funkelab/motile_tracker_bundled_app/.github/workflows/bundle_app.yml@main
+    secrets: inherit
+    with:
+      event_name: ${{ github.event_name }}

napari_track_edit-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,112 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"] # Push events to matching v*, i.e. v1.0, v20.15.10
+  pull_request: {}
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.platform }} py${{ matrix.python-version }} ${{ matrix.resolution }}
+    runs-on: ${{ matrix.platform }}
+    # Healthy runs finish in 5-12 minutes; without this a hang (e.g. a wgpu/tree-widget
+    # deadlock) burns the full 360-minute default before GitHub cancels it.
+    timeout-minutes: 30
+    env:
+      # disable resyncing on uv run
+      UV_NO_SYNC: "1"
+    strategy:
+      fail-fast: false
+      # OS-specific bugs are almost always Qt/GL-driver related and Python-version-
+      # agnostic, while version-specific bugs are language/stdlib related and OS-
+      # agnostic -- the two axes rarely interact, so we don't need their full cross:
+      #   - lowest-direct (oldest allowed deps) on all platforms, but only at our
+      #     floor Python (3.11, see requires-python) -- those dependency versions
+      #     predate 3.12/3.13 anyway, so testing them there too is redundant.
+      #   - highest deps on all platforms, but only at our newest Python (3.13).
+      #   - the remaining Python version (3.12) only on ubuntu (cheapest runner), as
+      #     a spot-check rather than a full platform cross.
+      matrix:
+        include:
+          - platform: ubuntu-latest
+            python-version: "3.11"
+            resolution: lowest-direct
+          - platform: macos-latest
+            python-version: "3.11"
+            resolution: lowest-direct
+          - platform: windows-latest
+            python-version: "3.11"
+            resolution: lowest-direct
+          - platform: ubuntu-latest
+            python-version: "3.12"
+            resolution: highest
+          - platform: ubuntu-latest
+            python-version: "3.13"
+            resolution: highest
+          - platform: macos-latest
+            python-version: "3.13"
+            resolution: highest
+          - platform: windows-latest
+            python-version: "3.13"
+            resolution: highest
+
+    steps:
+      - uses: actions/checkout@v7
+      # The Ubuntu runner image ships broken Microsoft apt repos whose signature
+      # is periodically invalid ("Clearsigned file isn't valid, got 'NOSPLIT'"),
+      # which fails the apt-get update inside setup-qt-libs. We don't need them.
+      - name: Remove broken Microsoft apt sources (ubuntu runner image)
+        if: runner.os == 'Linux'
+        run: |
+          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list \
+                     /etc/apt/sources.list.d/azure-cli.list \
+                     /etc/apt/sources.list.d/azure-cli.sources
+      - uses: tlambert03/setup-qt-libs@v1
+
+      # wgpu (via pygfx/fastplotlib, used by the tree view) needs a real Vulkan/GL
+      # adapter; Xvfb (below) only provides X11/GLX, not Vulkan. lavapipe/llvmpipe
+      # give it a software one, matching how pygfx/wgpu-py run their own Linux CI.
+      - name: Install llvmpipe and lavapipe for offscreen wgpu rendering
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update -y -qq
+          sudo apt-get install -y libegl1-mesa-dev libgl1-mesa-dri libxcb-xfixes0-dev mesa-vulkan-drivers
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --no-dev --group testing --resolution ${{ matrix.resolution }}
+
+      - name: Set Windows resolution
+        if: runner.os == 'Windows'
+        run: Set-DisplayResolution -Width 1920 -Height 1080 -Force
+        shell: powershell
+
+      - name: Install Windows OpenGL
+        if: runner.os == 'Windows'
+        run: |
+          git clone --depth 1 https://github.com/pyvista/gl-ci-helpers.git
+          powershell gl-ci-helpers/appveyor/install_opengl.ps1
+          if (Test-Path -Path "C:\Windows\system32\opengl32.dll" -PathType Leaf) {Exit 0} else {Exit 1}
+        shell: powershell
+
+      - name: Test
+        uses: aganders3/headless-gui@v2
+        with:
+          run: uv run pytest --color=yes --cov=napari_track_edit --cov-report=xml --cov-report=term-missing .
+
+      - name: Coverage
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: live-image-tracking-tools/napari-track-edit