DX: define developer environment with uv (#301)

Author: redeboer

.binder/apt.txt

@@ -0,0 +1 @@
+graphviz

.binder/postBuild

@@ -0,0 +1,12 @@
+#!/bin/bash
+set -ex
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source $HOME/.cargo/env
+uv export \
+  --extra jupyter \
+  --extra notebooks \
+  > requirements.txt
+uv pip install \
+  --requirement requirements.txt \
+  --system
+uv cache clean

.binder/runtime.txt

@@ -0,0 +1 @@
+python-3.12

.cspell.json

@@ -27,7 +27,6 @@
     "*.svg",
     ".editorconfig",
     ".envrc",
-    ".gitattributes",
     ".gitignore",
     ".pre-commit-config.yaml",
     ".prettierignore",
@@ -36,8 +35,7 @@
     "CITATION.cff",
     "docs/adr/*/*",
     "docs/conf.py",
-    "pyproject.toml",
-    "tox.ini"
+    "pyproject.toml"
   ],
   "language": "en-US",
   "words": [

.editorconfig

@@ -15,3 +15,6 @@ indent_size = 4
 
 [LICENSE]
 indent_size = unset
+
+[uv.lock]
+indent_size = 4

.envrc

@@ -1,10 +1,2 @@
-if [ -e .venv ]; then
-  source .venv/bin/activate
-elif [ -e venv ]; then
-  source venv/bin/activate
-elif [ -e .pixi ]; then
-  watch_file pixi.lock
-  eval "$(pixi shell-hook)"
-else
-  layout anaconda
-fi
+uv sync --all-extras --quiet
+source .venv/bin/activate

.gitattributes

@@ -9,8 +9,8 @@ on:
 jobs:
   milestone:
     if: startsWith(github.ref, 'refs/tags')
-    uses: ComPWA/actions/.github/workflows/close-milestone.yml@v1
+    uses: ComPWA/actions/.github/workflows/close-milestone.yml@v2
   push:
     if: startsWith(github.ref, 'refs/tags') && !github.event.release.prerelease
     secrets: inherit
-    uses: ComPWA/actions/.github/workflows/push-to-version-branches.yml@v1
+    uses: ComPWA/actions/.github/workflows/push-to-version-branches.yml@v2

.github/workflows/cd.yml

@@ -28,19 +28,16 @@ on:
 
 jobs:
   doc:
-    uses: ComPWA/actions/.github/workflows/ci-docs.yml@v1
+    uses: ComPWA/actions/.github/workflows/ci-docs.yml@v2
     permissions:
       pages: write
       id-token: write
     with:
       apt-packages: graphviz
       gh-pages: true
-      python-version: "3.12"
       specific-pip-packages: ${{ inputs.specific-pip-packages }}
   style:
     if: inputs.specific-pip-packages == ''
     secrets:
       token: ${{ secrets.PAT }}
-    uses: ComPWA/actions/.github/workflows/pre-commit.yml@v1
-    with:
-      python-version: "3.12"
+    uses: ComPWA/actions/.github/workflows/pre-commit.yml@v2

.github/workflows/ci.yml

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

.github/workflows/clean-caches.yml

@@ -1,4 +1,4 @@
-name: Requirements
+name: Update
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -12,12 +12,11 @@ on:
       - epic/*
     paths:
       - .pre-commit-config.yaml
-  schedule:
-    - cron: "0 3 7 */2 *"
+      - uv.lock
   workflow_dispatch:
 
 jobs:
-  requirements:
-    uses: ComPWA/actions/.github/workflows/requirements.yml@v1
+  lock:
+    uses: ComPWA/actions/.github/workflows/lock.yml@v2
     secrets:
       token: ${{ secrets.PAT }}

.github/workflows/requirements.yml renamed to .github/workflows/lock.yml

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

.github/workflows/pr-linting.yml

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

.github/workflows/release-drafter.yml

@@ -21,7 +21,6 @@ version.py
 
 # Temporary files
 *.pyc
-*condaenv.*
 .coverage
 .coverage.*
 .ipynb_checkpoints/
@@ -36,7 +35,6 @@ prof/
 
 # Virtual environments
 *venv/
-.pixi/
 .tox/
 pyvenv*/
 
@@ -53,6 +51,5 @@ pyvenv*/
 !.vscode/*.json
 !.zenodo.json
 !codecov.yml
-!environment.yml
 !pyrightconfig.json
 .jupyter_ystore.db

.gitignore

@@ -1,9 +1,10 @@
 ci:
-  autoupdate_commit_msg: "MAINT: autoupdate pre-commit hooks"
+  autoupdate_commit_msg: "MAINT: update lock files"
   autoupdate_schedule: quarterly
   skip:
     - check-jsonschema
     - pyright
+    - uv-lock
 
 repos:
   - repo: meta
@@ -12,14 +13,13 @@ repos:
       - id: check-useless-excludes
 
   - repo: https://github.com/ComPWA/policy
-    rev: 0.4.1
+    rev: 0.5.0
     hooks:
       - id: check-dev-files
         args:
           - --doc-apt-packages=graphviz
           - --dev-python-version=3.12
           - --github-pages
-          - --no-prettierrc
           - --no-pypi
           - --repo-name=compwa.github.io
           - --repo-title=ComPWA Organization
@@ -56,7 +56,7 @@ repos:
             metadata.vscode
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.4
+    rev: v0.7.0
     hooks:
       - id: ruff
         args: [--fix]
@@ -65,7 +65,7 @@ repos:
         types_or: [python, pyi, jupyter]
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-ast
       - id: check-case-conflict
@@ -106,7 +106,7 @@ repos:
         args: [--in-place]
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.29.2
+    rev: 0.29.4
     hooks:
       - id: check-jsonschema
         name: Check CITATION.cff
@@ -119,7 +119,7 @@ repos:
         pass_filenames: false
 
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v8.13.3
+    rev: v8.15.2
     hooks:
       - id: cspell
 
@@ -144,7 +144,12 @@ repos:
             docs/_static/favicon.ico
           )$
 
-  - repo: https://github.com/ComPWA/mirrors-pyright
-    rev: v1.1.379
+  - repo: https://github.com/ComPWA/pyright-pre-commit
+    rev: v1.1.385
     hooks:
       - id: pyright
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.4.25
+    hooks:
+      - id: uv-lock

.pre-commit-config.yaml

@@ -0,0 +1 @@
+3.12

.python-version

@@ -1,20 +1,17 @@
 version: 2
 
-sphinx:
-  builder: html
-  configuration: docs/conf.py
-  fail_on_warning: true
-
-formats:
-  - htmlzip
-
 build:
-  os: ubuntu-22.04
-  apt_packages:
-    - graphviz
+  os: ubuntu-24.04
   tools:
     python: "3.12"
-  jobs:
-    post_install:
-      - python -m pip install 'uv>=0.2.0'
-      - python -m uv pip install -e .[doc]
+  commands:
+    - |-
+      export PIXI_HOME=$READTHEDOCS_VIRTUALENV_PATH
+      curl -fsSL https://pixi.sh/install.sh | bash
+      pixi global install graphviz uv
+    - |-
+      export UV_LINK_MODE=copy
+      uv run --extra doc --locked --with tox \
+        tox -e doc
+      mkdir -p $READTHEDOCS_OUTPUT
+      mv docs/_build/html $READTHEDOCS_OUTPUT

.readthedocs.yml

@@ -30,9 +30,6 @@
     "\u03bd": true,
     "\u03c3": true
   },
-  "files.associations": {
-    "**/pixi.lock": "yaml"
-  },
   "files.watcherExclude": {
     "**/*_cache/**": true,
     "**/.eggs/**": true,
@@ -63,6 +60,9 @@
   "ruff.enable": true,
   "ruff.importStrategy": "fromEnvironment",
   "ruff.organizeImports": true,
+  "search.exclude": {
+    "**/uv.lock": true
+  },
   "telemetry.telemetryLevel": "off",
   "yaml.schemas": {
     "https://citation-file-format.github.io/1.2.0/schema.json": "CITATION.cff",

.vscode/settings.json

@@ -1,5 +1,26 @@
 # How to contribute?
 
-[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/compwa.github.io)
+[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://github.dev/ComPWA/compwa.github.io)
 
-This repository is part of the [ComPWA Organization](https://github.com/ComPWA). For more information about how to contribute to the packages, go to **[compwa.github.io/develop](https://compwa.github.io/develop)**!
+> [!TIP]
+> This package is part of the [ComPWA Organization](https://github.com/ComPWA). For more information about how to contribute to the packages, go to **[compwa.github.io/develop](https://compwa.github.io/develop)**!
+
+To contribute to the project, you need to install the package in a virtual environment. This can be done best with [`uv`](https://docs.astral.sh/uv) (see installation instructions [here](https://docs.astral.sh/uv/getting-started/installation)). For this, you first need to get the source code with [Git](https://git-scm.com):
+
+```shell
+git clone https://github.com/ComPWA/compwa.github.io
+cd compwa.github.io
+```
+
+Now it's simply a matter of creating and activating the [virtual environment](https://docs.astral.sh/uv/pip/environments) with [`uv sync`](https://docs.astral.sh/uv/reference/cli/#uv-sync). The dependencies for the project are 'pinned' in each commit through the [`uv.lock` file](https://docs.astral.sh/uv/concepts/projects/#project-lockfile).
+
+```shell
+uv sync
+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 [`pre-commit install`](https://pre-commit.com/#3-install-the-git-hook-scripts) **once**:
+
+```shell
+pre-commit install --install-hooks
+```

CONTRIBUTING.md

@@ -11,5 +11,6 @@
 [![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/master/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)
 
 This repository contains the source code for the [compwa.github.io](https://compwa.github.io) pages.

README.md

@@ -17,7 +17,7 @@
    },
    "outputs": [],
    "source": [
-    "%pip install -q expertsystem==0.6.10 graphviz==0.16"
+    "!uv pip install -q  expertsystem==0.6.10 graphviz==0.16"
    ]
   },
   {

docs/adr/001/operators.ipynb

@@ -35,7 +35,7 @@
    },
    "outputs": [],
    "source": [
-    "%pip install -q jax==0.2.13 jaxlib==0.1.67 matplotlib==3.4.2 numpy==1.19.5 protobuf==3.20.* sympy==1.8 tensorflow==2.4.*"
+    "!uv pip install -q  jax==0.2.13 jaxlib==0.1.67 matplotlib==3.4.2 numpy==1.19.5 protobuf==3.20.* sympy==1.8 tensorflow==2.4.*"
    ]
   },
   {

docs/adr/001/sympy.ipynb

@@ -35,7 +35,7 @@
    },
    "outputs": [],
    "source": [
-    "%pip install -q matplotlib==3.4.2 sympy==1.8"
+    "!uv pip install -q  matplotlib==3.4.2 sympy==1.8"
    ]
   },
   {
@@ -65,7 +65,7 @@
     "try:\n",
     "    from typing import Protocol\n",
     "except ImportError:\n",
-    "    from typing_extensions import Protocol"
+    "    from typing import Protocol"
    ]
   },
   {
@@ -190,7 +190,7 @@
     ") -> DynamicsExpression:\n",
     "    edge_ids = determine_attached_final_state(graph, edge_id)\n",
     "    final_state_ids = map(str, edge_ids)\n",
-    "    mass = sp.Symbol(f\"m_{{{'+'.join(final_state_ids)}}}\")\n",
+    "    mass = sp.Symbol(f\"m_{{{\"+\".join(final_state_ids)}}}\")\n",
     "    particle, _ = graph.get_edge_props(edge_id)\n",
     "    mass0 = sp.Symbol(f\"m_{{{particle.latex}}}\")\n",
     "    gamma0 = sp.Symbol(Rf\"\\Gamma_{{{particle.latex}}}\")\n",
@@ -212,7 +212,7 @@
     ") -> DynamicsExpression:\n",
     "    edge_ids = determine_attached_final_state(graph, edge_id)\n",
     "    final_state_ids = map(str, edge_ids)\n",
-    "    mass = sp.Symbol(f\"m_{{{'+'.join(final_state_ids)}}}\")\n",
+    "    mass = sp.Symbol(f\"m_{{{\"+\".join(final_state_ids)}}}\")\n",
     "    particle, _ = graph.get_edge_props(edge_id)\n",
     "    mass0 = sp.Symbol(f\"m_{{{particle.latex}}}\")\n",
     "    gamma0 = sp.Symbol(Rf\"\\Gamma_{{{particle.latex}}}\")\n",