ENH: generalize qrules.io.load() and write() signature

.cspell.json

@@ -26,6 +26,7 @@
     "*particle*.*ml",
     ".editorconfig",
     ".envrc",
+    ".github/dependabot.yml",
     ".gitignore",
     ".pre-commit-config.yaml",
     ".prettierignore",
@@ -39,7 +40,6 @@
     "typings"
   ],
   "ignoreWords": [
-    "MAINT",
     "adrs",
     "ampform",
     "arange",

.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+
+multi-ecosystem-groups:
+  lock:
+    assignees: [redeboer]
+    commit-message: { prefix: MAINT }
+    schedule: { interval: quarterly }
+
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    labels: [⬆️ Lock]
+    multi-ecosystem-group: lock
+    patterns: ["*"]
+  - package-ecosystem: uv
+    directory: "/"
+    labels: [⬆️ Lock]
+    multi-ecosystem-group: lock
+    patterns: ["*"]

.github/workflows/cd.yml

@@ -9,9 +9,9 @@ on:
 jobs:
   milestone:
     if: startsWith(github.ref, 'refs/tags')
-    uses: ComPWA/actions/.github/workflows/close-milestone.yml@v3
+    uses: ComPWA/actions/.github/workflows/close-milestone.yml@v4
   package-name:
-    uses: ComPWA/actions/.github/workflows/get-pypi-name.yml@v3
+    uses: ComPWA/actions/.github/workflows/get-pypi-name.yml@v4
   pypi:
     environment:
       name: PyPI
@@ -24,9 +24,9 @@ jobs:
       id-token: write
     runs-on: ubuntu-24.04
     steps:
-      - uses: ComPWA/actions/build-pypi-distribution@v3
+      - uses: ComPWA/actions/build-pypi-distribution@v4
       - uses: pypa/gh-action-pypi-publish@release/v1
   push:
     if: startsWith(github.ref, 'refs/tags') && !github.event.release.prerelease
     secrets: inherit
-    uses: ComPWA/actions/.github/workflows/push-to-version-branches.yml@v3
+    uses: ComPWA/actions/.github/workflows/push-to-version-branches.yml@v4

.github/workflows/ci.yml

@@ -17,32 +17,24 @@ on:
       - epic/*
       - "[0-9]+.[0-9]+.x"
   workflow_dispatch:
-    inputs:
-      specific-pip-packages:
-        description: Run CI with specific pip packages
-        required: false
-        type: string
 
 jobs:
   doc:
-    uses: ComPWA/actions/.github/workflows/ci-docs.yml@v3.0
+    uses: ComPWA/actions/.github/workflows/ci-docs.yml@v4.0
     permissions:
       pages: write
       id-token: write
     with:
       apt-packages: graphviz
-      specific-pip-packages: ${{ inputs.specific-pip-packages }}
-  pytest:
-    uses: ComPWA/actions/.github/workflows/pytest.yml@v3.0
-    with:
-      coverage-target: qrules
-      macos-python-version: "3.10"
-      specific-pip-packages: ${{ inputs.specific-pip-packages }}
-      test-output-path: tests/output/
-    secrets:
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
   style:
-    if: inputs.specific-pip-packages == ''
     secrets:
       token: ${{ secrets.PAT }}
-    uses: ComPWA/actions/.github/workflows/pre-commit.yml@v3.0
+    uses: ComPWA/actions/.github/workflows/pre-commit.yml@v4.0
+  test:
+    uses: ComPWA/actions/.github/workflows/test.yml@v4.0
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    with:
+      coverage-python-version: "3.13"
+      macos-python-version: "3.10"
+      test-output-path: tests/output/

.github/workflows/clean-caches.yml

@@ -14,9 +14,9 @@ on:
 jobs:
   cleanup:
     name: Remove caches
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-slim
     steps:
-      - uses: ComPWA/actions/clean-caches@v3
+      - uses: ComPWA/actions/clean-caches@v4
         with:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ref: ${{ inputs.ref }}

.github/workflows/lock.yml

@@ -17,6 +17,6 @@ on:
 
 jobs:
   lock:
-    uses: ComPWA/actions/.github/workflows/lock.yml@v3
+    uses: ComPWA/actions/.github/workflows/lock.yml@v4
     secrets:
       token: ${{ secrets.PAT }}

.github/workflows/pr-linting.yml

@@ -11,4 +11,4 @@ on:
 
 jobs:
   lint-pr:
-    uses: ComPWA/actions/.github/workflows/pr-linting.yml@v3
+    uses: ComPWA/actions/.github/workflows/pr-linting.yml@v4

.github/workflows/release-drafter.yml

@@ -9,7 +9,7 @@ on:
 
 jobs:
   update_release_draft:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-slim
     steps:
       - uses: release-drafter/release-drafter@v6
         env:

.pre-commit-config.yaml

@@ -1,7 +1,6 @@
 ci:
   autofix_commit_msg: "MAINT: implement pre-commit autofixes"
   autoupdate_commit_msg: "MAINT: upgrade lock files"
-  autoupdate_schedule: quarterly
   skip:
     - check-jsonschema
     - mypy
@@ -15,14 +14,15 @@ repos:
       - id: check-useless-excludes
 
   - repo: https://github.com/ComPWA/policy
-    rev: 0.7.3
+    rev: 0.8.2rc15
     hooks:
       - id: check-dev-files
         args:
           - --doc-apt-packages=graphviz
           - --repo-name=qrules
           - --repo-title=QRules
-          - --update-lock-files=outsource
+          - --type-checker=mypy
+          - --type-checker=pyright
       - id: colab-toc-visible
       - id: fix-nbformat-version
       - id: remove-empty-tags
@@ -32,9 +32,10 @@ repos:
           - --additional-packages=IPython
           - --extras-require=doc,viz
       - id: set-nb-display-name
+      - id: strip-nb-whitespace
 
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.8.1
+    rev: 0.9.0
     hooks:
       - id: nbstripout
         args:
@@ -62,7 +63,7 @@ repos:
             metadata.vscode
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.0
+    rev: v0.15.0
     hooks:
       - id: ruff-check
         args: [--fix]
@@ -94,7 +95,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/ComPWA/prettier-pre-commit
-    rev: v3.4.2
+    rev: v3.8.1
     hooks:
       - id: prettier
 
@@ -111,7 +112,7 @@ repos:
           - --in-place
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.34.1
+    rev: 0.36.1
     hooks:
       - id: check-jsonschema
         name: Check CITATION.cff
@@ -124,12 +125,12 @@ repos:
         pass_filenames: false
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v9.2.0
+    rev: v9.6.0
     hooks:
       - id: cspell
 
   - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
-    rev: 3.4.0
+    rev: 3.6.0
     hooks:
       - id: editorconfig-checker
         name: editorconfig
@@ -146,15 +147,14 @@ repos:
         entry: mypy
         language: system
         require_serial: true
-        types:
-          - python
+        types: [python]
 
   - repo: https://github.com/ComPWA/pyright-pre-commit
-    rev: v1.1.406
+    rev: v1.1.407
     hooks:
       - id: pyright
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.9.3
+    rev: 0.9.30
     hooks:
       - id: uv-lock

.readthedocs.yml

@@ -11,11 +11,7 @@ build:
       pixi global install graphviz uv
     - |-
       export UV_LINK_MODE=copy
-      uv run \
-        --group doc \
-        --no-dev \
-        --with poethepoet \
-        poe doc
+      uvx --from poethepoet poe doc
       mkdir -p $READTHEDOCS_OUTPUT
       mv docs/_build/html $READTHEDOCS_OUTPUT
 

.vscode/extensions.json

@@ -25,6 +25,7 @@
     "yzhang.markdown-all-in-one"
   ],
   "unwantedRecommendations": [
+    "astral-sh.ty",
     "bungcip.better-toml",
     "davidanson.vscode-markdownlint",
     "garaioag.garaio-vscode-unwanted-recommendations",

CONTRIBUTING.md

@@ -22,7 +22,7 @@ source .venv/bin/activate
 Formatting and linting checks are automatically performed when committing changes. This is done with [pre-commit](https://pre-commit.com). To install the hooks in your local repository, run install `pre-commit` with `uv`:
 
 ```shell
-uv tool install pre-commit --with pre-commit-uv --force-reinstall
+uv tool install pre-commit --with pre-commit-uv --force-reinstall --python=3.13
 ```
 
 and [`pre-commit install`](https://pre-commit.com/#3-install-the-git-hook-scripts) **once**:
@@ -31,7 +31,13 @@ and [`pre-commit install`](https://pre-commit.com/#3-install-the-git-hook-script
 pre-commit install --install-hooks
 ```
 
-[Poe the Poet](https://poethepoet.natn.io) is used as a task runner. You can see which local CI checks it defines by running
+[Poe the Poet](https://poethepoet.natn.io) is used as a task runner. Install it globally (within your home folder) with `uv`:
+
+```shell
+uv tool install poethepoet --force-reinstall --python=3.13
+```
+
+You can see which local CI checks it defines by running
 
 ```shell
 poe

README.md

@@ -14,9 +14,9 @@
 [![Documentation](https://readthedocs.org/projects/qrules/badge/?version=latest)](https://qrules.readthedocs.io)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/ComPWA/qrules/main.svg)](https://results.pre-commit.ci/latest/github/ComPWA/qrules/main)
 [![CI](https://github.com/ComPWA/qrules/actions/workflows/ci.yml/badge.svg)](https://github.com/ComPWA/qrules/actions/workflows/ci.yml)
-[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy.readthedocs.io)
+[![Type-checked with mypy](https://mypy-lang.org/static/mypy_badge.svg)](https://mypy.readthedocs.io)
 [![Test coverage](https://codecov.io/gh/ComPWA/qrules/branch/main/graph/badge.svg)](https://codecov.io/gh/ComPWA/qrules)
-[![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)
+[![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)

docs/conf.py

@@ -248,7 +248,6 @@ def __get_newtypes(some_type: type) -> list:
     "IPython": (f"https://ipython.readthedocs.io/en/{pin('IPython')}", None),
     "jsonschema": ("https://python-jsonschema.readthedocs.io/en/stable", None),
     "mypy": ("https://mypy.readthedocs.io/en/stable", None),
-    "pwa": ("https://pwa.readthedocs.io", None),
     "python": ("https://docs.python.org/3", None),
 }
 linkcheck_anchors = False
@@ -280,6 +279,9 @@ def __get_newtypes(some_type: type) -> list:
 nb_execution_show_tb = True
 nb_execution_timeout = -1
 nb_output_stderr = "remove"
+nitpick_ignore = [
+    ("py:class", "StrPath"),
+]
 nitpick_ignore_regex = [
     (r"py:(class|obj)", "json.encoder.JSONEncoder"),
     (r"py:(class|obj)", r"frozendict(\.frozendict)?"),
@@ -301,6 +303,7 @@ def __get_newtypes(some_type: type) -> list:
 pygments_style = "sphinx"
 release = get_package_version(PACKAGE)
 suppress_warnings = [
+    "myst.directive_unknown",
     "myst.domains",
     # skipping unknown output mime type: application/json
     # https://github.com/ComPWA/qrules/runs/8132605149?check_suite_focus=true#step:5:92

docs/index.md

@@ -47,7 +47,6 @@ QRules consists of three major components:
    one node (in correspondence to
    [Feynman graphs](https://en.wikipedia.org/wiki/Feynman_diagram)). This way, a graph
    describes the transition from one state to another.
-
    - **Edges** correspond to states (particles with spin). In other words, edges are a
      collection of properties such as the quantum numbers that characterize a state that
      the particle is in.

docs/usage.ipynb

@@ -118,7 +118,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, you use the {mod}`ampform` package to convert these transitions into a mathematical description that you can use to fit your data and perform {doc}`Partial Wave Analysis <pwa:index>`!"
+    "Next, you use the {mod}`ampform` package to convert these transitions into a mathematical description that you can use to fit your data and perform [partial-wave analysis](https://pwa.rtfd.io)!"
    ]
   },
   {
@@ -277,7 +277,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.8"
+   "version": "3.13.11"
   }
  },
  "nbformat": 4,

docs/usage/reaction.ipynb

@@ -61,7 +61,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A {doc}`Partial Wave Analysis <pwa:index>` starts by defining an amplitude model that describes the reaction process that is to be analyzed. Such a model is generally very complex and requires a fair amount of effort by the analyst (you). This gives a lot of room for mistakes.\n",
+    "A [partial-wave analysis](https://pwa.rtfd.io) starts by defining an amplitude model that describes the reaction process that is to be analyzed. Such a model is generally very complex and requires a fair amount of effort by the analyst (you). This gives a lot of room for mistakes.\n",
     "\n",
     "QRules is responsible to give you advice on the form of an amplitude model, based on the problem set you define (initial state, final state, allowed interactions, intermediate states, etc.). Internally, the system propagates the quantum numbers through the reaction graph while satisfying the specified conservation rules. How to control this procedure is explained in more detail below.\n",
     "\n",
@@ -620,7 +620,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.8"
+   "version": "3.13.11"
   }
  },
  "nbformat": 4,