dot-explorer 0.1.0__tar.gz

dot_explorer-0.1.0/.cargo/config.toml

@@ -0,0 +1,45 @@
+# Flags for building the Pyodide (browser) wheel.  The target Pyodide release
+# is 0.27.x (bundled by current Shinylive): CPython 3.12 + Emscripten 3.1.58,
+# so builds MUST use emsdk 3.1.58 exactly — a mismatched emcc version produces
+# a wheel whose platform tag micropip rejects at load time.
+#
+#   SIDE_MODULE=2          build a dynamic library loadable by Pyodide's main
+#                          module (=1 chokes on Rust's lib.rmeta)
+#   WASM_BIGINT            i64 <-> BigInt at the JS boundary
+#   relocation-model=pic   required for side modules (else R_WASM_TABLE_INDEX
+#                          link errors)
+#   link-native-libraries=no  stop rustc passing nonexistent emscripten C libs
+#                          to the linker (nightly-only -Z flag, so wasm builds
+#                          need a nightly toolchain).  Use the pinned
+#                          RUSTUP_TOOLCHAIN=nightly-2025-05-01: newer nightlies
+#                          default to wasm-exceptions (incompatible with
+#                          Pyodide 0.27's non-EH ABI); older ones predate
+#                          stdlib APIs used by bio 4.x.
+#
+# The earlier opt-level=0 workaround (emsdk 3.1.65's wasm-opt not knowing
+# --enable-bulk-memory-opt) is no longer needed on 3.1.58.
+[target.wasm32-unknown-emscripten]
+rustflags = [
+  "-C", "link-arg=-sSIDE_MODULE=2",
+  "-C", "link-arg=-sWASM_BIGINT",
+  "-C", "relocation-model=pic",
+  "-Z", "link-native-libraries=no",
+  # Appended after rustc's own "-O3", so emcc links at -O0 and skips its
+  # wasm-opt post-processing pass entirely (modern LLVM emits the
+  # bulk-memory-opt feature, which emsdk 3.1.58's bundled wasm-opt rejects
+  # with "Unknown option '--enable-bulk-memory-opt'").  The Rust code itself
+  # is still compiled at opt-level 3 — only the binaryen pass is skipped.
+  "-C", "link-arg=-O0",
+]
+
+# On macOS, the pyo3 `extension-module` cdylib leaves Python symbols undefined
+# to be resolved by the host interpreter at load time.  Standalone `cargo`
+# invocations (`test`, `bench`, `build`) that link that cdylib need the linker
+# told to allow those undefined symbols, or the link fails.  These entries are
+# target-scoped to macOS and do not affect Linux CI, wasm, or the maturin wheel
+# build (which sets its own linker args).
+[target.x86_64-apple-darwin]
+rustflags = ["-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup"]
+
+[target.aarch64-apple-darwin]
+rustflags = ["-C", "link-arg=-undefined", "-C", "link-arg=dynamic_lookup"]

dot_explorer-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ""
+labels: ""
+assignees: ""
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. When I run this command `...`
+2. With these input files: [Attach sample minimal input files if applicable]
+3. I get the following error:
+
+```code
+YOUR ERROR MESSAGE HERE
+```
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+
+- Python version: [output of `python --version`]
+- Platform: [output of `uname -a` or `systeminfo`]
+
+**System information**
+
+- OS: [e.g. MacOS, Windows, Ubuntu]
+- Version [e.g. Sequoia 15.1.1, Windows 10, Ubuntu 20.04]
+- Processor: [e.g. Intel i7, AMD Ryzen 5]
+
+**Additional context**
+Add any other context about the problem here.

dot_explorer-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ""
+labels: ""
+assignees: ""
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

dot_explorer-0.1.0/.github/dependabot.yml

@@ -0,0 +1,35 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      monthly-batch:
+        patterns:
+          - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      monthly-batch:
+        patterns:
+          - "*"
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "monthly" # Choose daily, weekly, or monthly
+    groups:
+      monthly-batch:
+        patterns:
+          - "*"
+#  - package-ecosystem: "pip"
+#    directory: "/" # Location of pyproject.toml for Python dependencies
+#    schedule:
+#      interval: "weekly"

dot_explorer-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,81 @@
+## What and why
+
+<!-- What does this change, and what problem does it solve?  Link any issue:
+     "Fixes #123" / "Part of #123". -->
+
+## Type of change
+
+<!-- Tick all that apply.  The PR title is squash-merged as the commit message,
+     so please make it a Conventional Commit line, e.g.
+     `feat(app): colour alignments by identity` or `fix(plot): ...`.
+     Use `!` (`refactor!:`) for a breaking change. -->
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Performance
+- [ ] Documentation
+- [ ] Build / CI / dependencies
+- [ ] Breaking change (API, CLI, or output format)
+
+## How was this tested?
+
+<!-- New/updated tests, and anything you checked by hand (e.g. rendered a plot,
+     ran the app, opened an HTML report). -->
+
+## Checklist
+
+- [ ] `cargo fmt --all -- --check`, `cargo clippy -- -D warnings` and `cargo test` pass
+- [ ] `ruff format`/`ruff check` clean and `pytest tests/ -v` passes
+- [ ] Tests added or updated for the change
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]`
+- [ ] Docs updated (`docs/`, module docstrings, or `app/README.md`) if behaviour changed
+
+## Project-specific checks
+
+<!-- Delete the sections that do not apply to this PR. -->
+
+**Touched `src/*.rs`**
+
+- [ ] Rebuilt with `maturin develop` and re-ran the Python suite
+- [ ] New `needletail` / `rayon` use is `#[cfg(feature = ...)]`-gated, and Python
+      callers degrade gracefully without it (the wasm build uses
+      `--no-default-features`)
+- [ ] `python/dot_explorer/_dot_explorer.pyi` stubs updated to match any changed
+      signature
+- [ ] Nothing added that holds GIL-bound cross-call state (statics,
+      `GILOnceCell`, `thread_local`, `unsendable` pyclasses) — the module is
+      declared `gil_used = false`
+
+**Touched the matching or contig-ordering path**
+
+- [ ] `tests/test_kmer_index_parity.py` still passes unchanged
+- [ ] Gravity ordering changed in *both* engines (Rust
+      `SequenceIndex.optimal_contig_order` and Python
+      `paf_io.compute_gravity_contigs`), with
+      `tests/test_gravity_parity.py` passing
+
+**Performance-sensitive change**
+
+- [ ] Benchmark numbers included below (`cargo bench`, `pytest python/benchmarks
+      --codspeed`, and/or `python scripts/mem_profile_index.py`) — memory counts
+      as much as speed, since the browser app runs in a ~4 GB wasm heap
+
+**Touched `app/`**
+
+- [ ] Logic went in `app/core/` (with tests in `tests/test_app_*.py`), not
+      `app/app.py`
+- [ ] Verified natively (`shiny run app/app.py`)
+- [ ] Verified in a Shinylive export, if the change could behave differently
+      under Pyodide (no threads, no native FASTA reader, sourmash 4.8 APIs only)
+- [ ] Pinned wasm toolchain versions unchanged, or the change is explained in
+      the PR body (see `app/README.md`)
+
+**Touched clustering / similarity**
+
+- [ ] Restricted to sourmash 4.8-era APIs (Pyodide bundles 4.8.11)
+- [ ] Optional imports still `importorskip`-ed so the suite runs without the
+      `cluster` extra
+
+**Touched `docs/tutorials/`**
+
+- [ ] Edited the `.ipynb` notebooks, not the generated `.md` build products

dot_explorer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,279 @@
+name: CI
+
+on:
+  # Trigger on push to main (post-merge) and on all pull requests to main.
+  # Omitting push to feature branches avoids duplicate runs when a PR is open.
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  rust-tests:
+    name: Rust Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+      - name: Add clippy and rustfmt components
+        run: |
+          rustup component add clippy
+          rustup component add rustfmt
+      - name: Cache cargo registry
+        uses: actions/cache@v6
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+      - name: Check formatting
+        run: cargo fmt -- --check
+      - name: Run clippy
+        run: cargo clippy -- -D warnings
+      - name: Run cargo tests
+        run: cargo test
+      - name: Run cargo check
+        run: cargo check
+
+  version-check:
+    name: Version Stamp Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Full history + tags: scripts/stamp_version.py derives the
+          # version from `git describe`.
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Check stamped versions match the latest tag
+        run: python scripts/stamp_version.py --check
+
+  python-lint:
+    name: Python Lint and Format
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.sha }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: astral-sh/ruff-action@v3
+        with:
+          src: "./python ./tests"
+          args: "format"
+      - uses: astral-sh/ruff-action@v3
+        with:
+          src: "./python ./tests"
+          args: "check --fix"
+      - uses: isort/isort-action@v1
+        with:
+          configuration: "--settings-path=./pyproject.toml"
+          paths: "./python ./tests"
+      - uses: stefanzweifel/git-auto-commit-action@v7
+        id: auto-commit-action
+        with:
+          commit_message: "Style fixes by Ruff"
+
+  python-tests:
+    name: Python Tests
+    runs-on: ubuntu-latest
+    needs: rust-tests
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+      - name: Cache cargo registry
+        uses: actions/cache@v6
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+      - name: Install maturin and dependencies
+        # sourmash + scipy cover the `cluster` extra (tests/test_similarity.py
+        # and friends importorskip them, so a failed install only skips).
+        run: |
+          pip install maturin pytest pytest-cov matplotlib numpy shiny pyfaidx sourmash scipy
+      - name: Build and install dot-explorer
+        run: |
+          maturin build --release
+          pip install target/wheels/*.whl
+      - name: Run pytest
+        run: pytest tests/ -v
+
+  python-tests-freethreaded:
+    name: Python Tests (free-threaded 3.14t)
+    runs-on: ubuntu-latest
+    needs: rust-tests
+    env:
+      # Refuse to let the interpreter quietly turn the GIL back on, and warn on
+      # any extension that has not opted into free-threading.
+      PYTHON_GIL: "0"
+      PYTHONWARNDEFAULTTHREADSAFETY: "1"
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up free-threaded Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.14t"
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+      - name: Cache cargo registry
+        uses: actions/cache@v6
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-ft-${{ hashFiles('**/Cargo.lock') }}
+      - name: Install maturin and dependencies
+        # No shiny here, unlike the GIL build: it pulls orjson, which has no
+        # free-threaded wheel and fails to build from source.  The suite does
+        # not need it (same 741 passed / 6 skipped either way).  pyfaidx is
+        # pure Python, so it is safe on 3.14t (tests/test_app_seqs.py).
+        # sourmash ships abi-agnostic (py2.py3, CFFI) wheels and scipy has
+        # cp314t wheels, so the cluster extra runs here too; the similarity
+        # tests importorskip them if either install ever breaks.
+        run: |
+          pip install maturin pytest pytest-cov matplotlib numpy pyfaidx sourmash scipy
+      - name: Clean wheels directory
+        run: rm -rf target/wheels/
+      - name: Build and install dot-explorer
+        # The wheel is tagged cp314-cp314t (python tag cp314, abi tag cp314t).
+        run: |
+          maturin build --release
+          pip install target/wheels/*cp314t*.whl
+      - name: Assert the extension does not re-enable the GIL
+        # src/lib.rs declares #[pymodule(gil_used = false)].  If that is ever
+        # dropped, importing the module flips the GIL back on and the cp314t
+        # wheel we publish is free-threaded in name only -- fail here instead.
+        run: |
+          python -c "import sys, dot_explorer; assert not sys._is_gil_enabled(), 'GIL re-enabled on import'"
+      - name: Run pytest
+        run: pytest tests/ -v
+
+  native-wheel-build:
+    name: Native Wheel Build
+    runs-on: ubuntu-latest
+    needs: rust-tests
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - name: Cache cargo registry
+        uses: actions/cache@v6
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+      - name: Install maturin
+        run: pip install maturin
+      - name: Build native wheel
+        run: maturin build --release
+      - name: Upload native wheel artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: native-wheel
+          path: target/wheels/*.whl
+
+  wasm-build:
+    name: Wasm (Pyodide) Wheel Build
+    runs-on: ubuntu-latest
+    # Run independently; a wasm build failure does not block other jobs.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install Rust nightly with wasm32-unknown-emscripten target
+        # Nightly is required by the -Z link-native-libraries=no flag in
+        # .cargo/config.toml.  Pinned to nightly-2025-05-01: newer nightlies
+        # emit wasm-exceptions by default (incompatible with Pyodide 0.27's
+        # non-EH ABI), while older ones predate stdlib APIs our deps use
+        # (bio 4.x needs is_multiple_of, stabilised in Rust 1.87).
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: nightly-2025-05-01
+          targets: wasm32-unknown-emscripten
+      - name: Set up Emscripten SDK
+        uses: mymindstorm/setup-emsdk@v16
+        with:
+          # MUST match the Emscripten version of the target Pyodide release.
+          # Pyodide 0.27.x (bundled by current Shinylive) = emsdk 3.1.58.
+          # The wheel platform tag derives from this version and micropip
+          # rejects mismatches.
+          version: 3.1.58
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          # Pinned to 3.12: Pyodide 0.27 ships CPython 3.12.7, so the wasm
+          # wheel must be built against a matching interpreter version.
+          python-version: "3.12"
+      - name: Cache cargo registry
+        uses: actions/cache@v6
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-wasm-cargo-${{ hashFiles('**/Cargo.lock') }}
+      - name: Install maturin
+        run: pip install maturin
+      - name: Build wasm wheel
+        # rm: the cargo cache restores target/wheels from earlier runs
+        # (other Emscripten versions); stale wheels must not reach the
+        # artifact (one previously shipped inside the deployed app).
+        run: >
+          rm -rf target/wheels &&
+          maturin build --release
+          --target wasm32-unknown-emscripten
+          --no-default-features
+          -i python3.12
+      - name: Check wheel platform tag
+        run: |
+          ls target/wheels/
+          ls target/wheels/*cp312-cp312-emscripten_3_1_58_wasm32.whl
+      - name: Smoke-test wheel under Pyodide (Node)
+        run: |
+          npm install pyodide@0.27.7
+          node scripts/wasm_smoke_test.mjs target/wheels/*cp312*emscripten*.whl
+      - name: Upload wasm wheel artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: wasm-wheel
+          path: target/wheels/*cp312-cp312-emscripten_3_1_58_wasm32.whl
+
+  docs-build:
+    name: Docs Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install docs dependencies
+        # Builds the compiled extension too: mkdocstrings imports dot_explorer
+        # to document it.
+        run: pip install ".[docs]"
+      - name: Render tutorial notebooks to Markdown
+        run: python scripts/notebooks_to_md.py
+      - name: Build docs site
+        # Same command as the deploy workflow, minus the app export.
+        run: zensical build --clean --strict

dot_explorer-0.1.0/.github/workflows/citation-cff.yml

@@ -0,0 +1,45 @@
+name: Citation CFF
+
+on:
+  push:
+    paths:
+      - CITATION.cff
+    tags:
+      # Match semantic version tags: v1.0.0, v1.2.3, v2.0.0-beta, etc.
+      # Excludes moving tags: v1, v2
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  validate:
+    name: Validate CITATION.cff
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Validate CITATION.cff
+        uses: dieghernan/cff-validator@v5
+        env:
+          GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+  update:
+    name: Update CITATION.cff
+    runs-on: ubuntu-latest
+    needs: validate
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Sync version and date in CITATION.cff
+        uses: Adamtaranto/citation-sync-action@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          # Create PR instead of pushing to main
+          use-pull-request: true
+          update-mode: "match"

dot_explorer-0.1.0/.github/workflows/codspeed.yml

@@ -0,0 +1,75 @@
+name: CodSpeed
+on:
+#  push:
+#    branches: [main]
+  pull_request:
+    branches: [main]
+    paths:
+      - "benches/**"
+      - "src/**"
+      - "python/**"
+      - ".github/workflows/codspeed.yml"
+  # `workflow_dispatch` allows CodSpeed to trigger backtest
+  # performance analysis in order to generate initial data.
+  workflow_dispatch:
+concurrency:
+  group: codspeed-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+  id-token: write # for OpenID Connect authentication with CodSpeed
+jobs:
+  rust-benchmarks:
+    if: ${{ github.actor != 'dependabot[bot]' }} # Do not run on commits created by dependabot
+    name: Rust benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      # The bench binary links `_dot_explorer` (an rlib), which pulls in pyo3 built
+      # without the `extension-module` feature, so it dynamically links
+      # libpython. Pin the interpreter for the build and expose its lib dir so
+      # the loader can find libpython when `cargo codspeed run` executes the
+      # bench binary. Without this the run relies on the runner's default
+      # library path, which is not guaranteed.
+      - name: Expose libpython for the pyo3-linked bench binary
+        run: |
+          echo "PYO3_PYTHON=$(which python)" >> "$GITHUB_ENV"
+          echo "LD_LIBRARY_PATH=$(python -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR"))')${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" >> "$GITHUB_ENV"
+      - name: Setup rust toolchain, cache and cargo-codspeed binary
+        uses: moonrepo/setup-rust@v1
+        with:
+          channel: stable
+          cache-target: release
+          bins: cargo-codspeed
+      - name: Build the benchmark target(s)
+        run: cargo codspeed build
+      - name: Run the benchmarks
+        uses: CodSpeedHQ/action@v5
+        with:
+          mode: simulation
+          run: cargo codspeed run
+  python-benchmarks:
+    if: ${{ github.actor != 'dependabot[bot]' }} # Do not run on commits created by dependabot
+    name: Python benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      # maturin needs cargo to build the extension from the sdist/source tree.
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Build dot-explorer and install benchmark dependencies
+        # The maturin build backend compiles the extension; .[test] also pulls
+        # in pytest and pytest-codspeed.
+        run: |
+          python -m pip install --upgrade pip
+          pip install '.[test]'
+      - name: Run the benchmarks
+        uses: CodSpeedHQ/action@v5
+        with:
+          mode: simulation
+          run: pytest python/benchmarks --codspeed