scverse-backends 0.0.2__tar.gz

scverse_backends-0.0.2/.github/workflows/ci.yaml

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: "1"
+  UV_COMPILE_BYTECODE: "1"
+
+defaults:
+  run:
+    shell: bash -euo pipefail {0}
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          filter: blob:none
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          cache-dependency-glob: pyproject.toml
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+
+  get-test-environments:
+    name: Get Test Environments
+    runs-on: ubuntu-latest
+    outputs:
+      envs: ${{ steps.get-envs.outputs.envs }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          filter: blob:none
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: false
+      - name: Read hatch test matrix
+        id: get-envs
+        run: |
+          ENVS_JSON=$(NO_COLOR=1 uvx hatch env show --json | jq -c 'to_entries
+            | map(
+                select(.key | startswith("hatch-test"))
+                | {
+                    name: .key,
+                    python: .value.python,
+                    coverage: (.value.python == "3.14")
+                  }
+              )')
+          echo "envs=${ENVS_JSON}" | tee "$GITHUB_OUTPUT"
+
+  test:
+    name: Test (${{ matrix.env.name }})
+    needs: get-test-environments
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    strategy:
+      fail-fast: false
+      matrix:
+        env: ${{ fromJSON(needs.get-test-environments.outputs.envs) }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          filter: blob:none
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.env.python }}
+          cache-dependency-glob: |
+            pyproject.toml
+            hatch.toml
+      - name: Run tests
+        run: |
+          mkdir -p test-data
+          if [[ "${{ matrix.env.coverage }}" == "true" ]]; then
+            uvx hatch run ${{ matrix.env.name }}:run-cov --junitxml=test-data/test-results.xml
+          else
+            uvx hatch run ${{ matrix.env.name }}:run --junitxml=test-data/test-results.xml
+          fi
+      - name: Upload coverage
+        if: ${{ !cancelled() && matrix.env.coverage }}
+        uses: codecov/codecov-action@v6
+        with:
+          fail_ci_if_error: true
+          files: coverage.xml
+          flags: ${{ matrix.env.name }}
+          use_oidc: true
+      - name: Upload test results
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v6
+        with:
+          fail_ci_if_error: true
+          files: test-data/test-results.xml
+          flags: ${{ matrix.env.name }}
+          report_type: test_results
+          use_oidc: true
+
+  all-green:
+    name: All CI Green
+    if: always()
+    needs:
+      - build
+      - get-test-environments
+      - test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}

scverse_backends-0.0.2/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

scverse_backends-0.0.2/.gitignore

@@ -0,0 +1,144 @@
+# --- OS noise ---
+.DS_Store
+._*
+.AppleDouble
+.LSOverride
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+ehthumbs_vista.db
+Desktop.ini
+$RECYCLE.BIN/
+*~
+.nfs*
+.fuse_hidden*
+.directory
+.Trash-*
+
+# --- Editors / IDEs ---
+.vscode/
+.idea/
+*.iml
+*.swp
+*.swo
+.*.sw?
+*.sublime-project
+*.sublime-workspace
+.project
+.pydevproject
+.spyderproject
+.spyproject
+.ropeproject
+.netrwhist
+.tags
+tags
+TAGS
+
+# --- Coding agents (don't commit local agent state, prompts, or memory) ---
+CLAUDE.md
+.claude/
+.claude.json
+.claudeignore
+.cursor/
+.cursorrules
+.cursorignore
+.aider*
+.aider.tags.cache.v3/
+.copilot-instructions.md
+.github/copilot-instructions.md
+.windsurf/
+.windsurfrules
+.codeium/
+.continue/
+.ai/
+.amazonq/
+.tabnine/
+.cody/
+.cline/
+.zed/
+.roo/
+.bolt/
+.devin/
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg
+*.egg-info/
+.eggs/
+develop-eggs/
+downloads/
+eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.manifest
+*.spec
+pip-log.txt
+pip-delete-this-directory.txt
+MANIFEST
+
+# --- Virtual environments ---
+.env
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.python-version
+
+# --- Build / packaging ---
+build/
+dist/
+src/scverse_backends/_version.py
+
+# --- Testing / type-checking / linting caches ---
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache/
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+test-data/
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+cython_debug/
+htmlcov/
+cover/
+
+# --- Jupyter ---
+.ipynb_checkpoints/
+profile_default/
+ipython_config.py
+
+# --- Docs ---
+docs/_build/
+docs/generated/
+docs/jupyter_execute/
+
+# --- direnv / asdf / mise ---
+.envrc
+.tool-versions
+.mise.toml
+
+# --- node (if anyone vendors a JS toolchain) ---
+node_modules/
+PanGPA.log

scverse_backends-0.0.2/.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+ci:
+    autofix_commit_msg: "style: apply pre-commit fixes"
+    autoupdate_commit_msg: "chore: update pre-commit hooks"
+    autoupdate_schedule: monthly
+
+repos:
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+    -   id: ruff-check
+        args: ["--fix"]
+    -   id: ruff-format
+    # The following can be removed once PLR0917 is out of preview
+    -   name: ruff preview rules
+        id: ruff-check
+        args: ["--preview", "--select=PLR0917"]
+-   repo: local
+    hooks:
+    -   id: ty-check
+        name: ty check
+        entry: ty check src
+        language: python
+        additional_dependencies:
+        - ty==0.0.34
+        pass_filenames: false
+-   repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+    -   id: taplo-format
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-added-large-files
+    -   id: check-case-conflict
+    -   id: check-toml
+    -   id: check-yaml
+    -   id: check-merge-conflict
+    -   id: no-commit-to-branch
+        args: [--branch=main]
+    -   id: detect-private-key
+-   repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+    -   id: codespell
+        additional_dependencies:
+        - tomli

scverse_backends-0.0.2/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

scverse_backends-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scverse®
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scverse_backends-0.0.2/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: scverse-backends
+Version: 0.0.2
+Summary: Pluggable backend dispatch for scverse and scientific Python host libraries
+Project-URL: Bug Tracker, https://github.com/scverse/scverse-backends/issues
+Project-URL: Source, https://github.com/scverse/scverse-backends
+Author: scverse
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backend-dispatch,scverse,single-cell
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: hatch>=1.9; extra == 'dev'
+Requires-Dist: pre-commit>=3; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: ty==0.0.34; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2; extra == 'docs'
+Requires-Dist: scanpydoc[theme]>=0.13; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=2; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx-design>=0.5; extra == 'docs'
+Requires-Dist: sphinx>=7; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# scverse-backends
+
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/scverse/scverse-backends/main.svg)](https://results.pre-commit.ci/latest/github/scverse/scverse-backends/main)
+[![codecov](https://codecov.io/gh/scverse/scverse-backends/graph/badge.svg?token=BMSUQWKIN8)](https://codecov.io/gh/scverse/scverse-backends)
+[![Documentation Status](https://readthedocs.org/projects/scverse-backends/badge/?version=latest)](https://scverse-backends.readthedocs.io/en/latest/?badge=latest)
+
+> ⚠️ **Under active development.** APIs may shift.
+
+The default plugin & dispatch mechanism for [scverse](https://scverse.org).
+Any host library decorates its public functions with `@backend_dispatch`; any
+backend — GPU, distributed, JAX, PyTorch, anything
+— plugs in via a Python entrypoint and gets picked up automatically.
+
+Want to add a PyTorch backend, a JAX backend, your own custom one?
+**You don't need a PR against the host.** Ship a package that exposes
+a module or object with `name`, `aliases`, and host-named callables,
+register it as an entry point, and users install it next to the host.
+That's the whole contract.
+
+```python
+import example_host as eh
+
+with eh.settings.use_backend("accelerated"):
+    eh.some_function(data)
+```
+
+## Status
+
+- Built from backend-dispatch prototypes in scverse host integrations.
+- Concrete backend aliases belong in host integrations, not in this infrastructure package.
+- Goal: host libraries depend on this package and stop re-rolling their own dispatch.
+
+## Docs
+
+Full docs at [scverse-backends.readthedocs.io](https://scverse-backends.readthedocs.io/en/latest/).
+
+## License
+
+MIT.

scverse_backends-0.0.2/README.md

@@ -0,0 +1,39 @@
+# scverse-backends
+
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/scverse/scverse-backends/main.svg)](https://results.pre-commit.ci/latest/github/scverse/scverse-backends/main)
+[![codecov](https://codecov.io/gh/scverse/scverse-backends/graph/badge.svg?token=BMSUQWKIN8)](https://codecov.io/gh/scverse/scverse-backends)
+[![Documentation Status](https://readthedocs.org/projects/scverse-backends/badge/?version=latest)](https://scverse-backends.readthedocs.io/en/latest/?badge=latest)
+
+> ⚠️ **Under active development.** APIs may shift.
+
+The default plugin & dispatch mechanism for [scverse](https://scverse.org).
+Any host library decorates its public functions with `@backend_dispatch`; any
+backend — GPU, distributed, JAX, PyTorch, anything
+— plugs in via a Python entrypoint and gets picked up automatically.
+
+Want to add a PyTorch backend, a JAX backend, your own custom one?
+**You don't need a PR against the host.** Ship a package that exposes
+a module or object with `name`, `aliases`, and host-named callables,
+register it as an entry point, and users install it next to the host.
+That's the whole contract.
+
+```python
+import example_host as eh
+
+with eh.settings.use_backend("accelerated"):
+    eh.some_function(data)
+```
+
+## Status
+
+- Built from backend-dispatch prototypes in scverse host integrations.
+- Concrete backend aliases belong in host integrations, not in this infrastructure package.
+- Goal: host libraries depend on this package and stop re-rolling their own dispatch.
+
+## Docs
+
+Full docs at [scverse-backends.readthedocs.io](https://scverse-backends.readthedocs.io/en/latest/).
+
+## License
+
+MIT.

scverse_backends-0.0.2/codecov.yml

@@ -0,0 +1,21 @@
+codecov:
+  require_ci_to_pass: true
+
+coverage:
+  precision: 2
+  round: down
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 2%
+    patch:
+      default:
+        target: 80%
+        threshold: 5%
+    changes: false
+
+comment:
+  layout: "diff, flags, files"
+  behavior: default
+  require_changes: true

scverse_backends-0.0.2/docs/Makefile

@@ -0,0 +1,18 @@
+SPHINXOPTS    ?= -W --keep-going
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help clean html livehtml
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean:
+	rm -rf "$(BUILDDIR)" generated
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)

scverse_backends-0.0.2/docs/api.md

@@ -0,0 +1,26 @@
+# API reference
+
+## Public API
+
+```{eval-rst}
+.. currentmodule:: scverse_backends
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   BackendDispatcher
+   Settings
+```
+
+## Testing utilities
+
+```{eval-rst}
+.. currentmodule:: scverse_backends.testing
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   run_conformance
+```

scverse_backends-0.0.2/docs/conf.py

@@ -0,0 +1,85 @@
+"""Sphinx configuration for scverse-backends."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from importlib.metadata import metadata
+
+# -- Project metadata --------------------------------------------------------
+info = metadata("scverse-backends")
+project = info["Name"]
+author = "scverse"
+copyright = f"{datetime.now():%Y}, {author}"
+release = info["Version"]
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "scanpydoc",
+]
+
+master_doc = "index"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+templates_path = ["_templates"]
+suppress_warnings = ["myst.header"]
+
+# -- MyST --------------------------------------------------------------------
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "smartquotes",
+    "substitution",
+]
+myst_heading_anchors = 3
+
+# -- Autodoc -----------------------------------------------------------------
+autosummary_generate = True
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+}
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+typehints_defaults = "comma"
+always_document_param_types = True
+
+# -- Intersphinx -------------------------------------------------------------
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# -- HTML output -------------------------------------------------------------
+html_theme = "scanpydoc"
+html_title = "scverse-backends"
+html_static_path = ["_static"]
+html_show_sphinx = False
+pygments_style = "default"
+pygments_dark_style = "native"
+
+html_theme_options = {
+    "repository_url": "https://github.com/scverse/scverse-backends",
+    "repository_branch": "main",
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "use_edit_page_button": True,
+    "path_to_docs": "docs",
+    "navigation_with_keys": False,
+}
+
+html_context = {
+    "github_user": "scverse",
+    "github_repo": "scverse-backends",
+    "github_version": "main",
+    "doc_path": "docs",
+}