From d6fb95a6c0f0902b892c9721be5b4b0a9fa50db2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Val=C3=A9rian=20Rey?= Date: Wed, 29 Oct 2025 15:05:56 +0100 Subject: [PATCH 1/6] chore: Update doc dependency caps * Uncap furo (our sphinx theme): it just changes color of already-clicked links, which is not that bad IMO (and we can probably override this). * Increase lower cap of sphinx-autodoc-typehints. Before 3.5.0, it's not compatible with Python 3.14. --- pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index d1773b68..62ea34f7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -71,9 +71,9 @@ check = [ doc = [ "sphinx>=6.0, !=7.2.0, !=7.2.1, !=7.2.3, !=7.2.4, !=7.2.5", # Versions in [7.2.0, 7.2.5] have a bug with an internal torch import from _C - "furo>=2023.0, <2024.04.27", # Force it to be recent so that the theme looks better, 2024.04.27 seems to have bugged link colors + "furo>=2023.0", # Force it to be recent so that the theme looks better "tomli>=1.1", # The load function doesn't work similarly before 1.1 - "sphinx-autodoc-typehints>=1.16.0", # Some problems with TypeVars before 1.16 + "sphinx-autodoc-typehints>=3.5.0", # Bugged Union on Python 3.14 before 3.5.0 "myst-parser>=3.0.1", # Never tested lower versions "sphinx-design>=0.6.0", # Never tested lower versions ] From b205efcd09dcac79f1b42cdf37e93b1a00ea9a23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Val=C3=A9rian=20Rey?= Date: Wed, 29 Oct 2025 15:58:32 +0100 Subject: [PATCH 2/6] Fix uv resolving for the whole range of python versions. * uv somehow decides to constrain libraries to be compatible with the whole range of python versions supported by torchjd (3.10-3.13) when resolving, so it does not install libraries that require python 3.11+ for example, even when using python 3.13. This leads to outdated library versions installed in the CI and locally, especially documentation-related libraries. * Adding --python-version=... forces uv to resolve libraries compatible with the specified python version only, fixing the issue * When using `uv run ...`, uv automatically re-syncs. There's no way to specify the python-version for which to resolve when this happens, so the idea is to prevent this resyncing by either using --no-sync everytime we call uv run, or by using the UV_NO_SYNC=1 environment variable. This is done in both ci files that have a uv run, and it's now recommended in CONTRIBUTING.md --- .github/workflows/build-deploy-docs.yml | 5 ++++- .github/workflows/tests.yml | 11 +++++++---- CONTRIBUTING.md | 18 ++++++++++++++++-- 3 files changed, 27 insertions(+), 7 deletions(-) diff --git a/.github/workflows/build-deploy-docs.yml b/.github/workflows/build-deploy-docs.yml index 4ddf9e22..0db11ae5 100644 --- a/.github/workflows/build-deploy-docs.yml +++ b/.github/workflows/build-deploy-docs.yml @@ -6,6 +6,9 @@ on: tags: - 'v[0-9]*.[0-9]*.[0-9]*' +env: + UV_NO_SYNC: 1 + jobs: build-deploy-doc: name: Build & deploy doc @@ -23,7 +26,7 @@ jobs: python-version: '3.13' - name: Install dependencies (default with full options & doc) - run: uv pip install '.[full]' --group doc + run: uv pip install --python-version=${{ inputs.python-version }} '.[full]' --group doc - name: Determine deployment folder id: deploy_folder diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index fdf465f9..9c273e94 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -6,6 +6,9 @@ on: schedule: - cron: '41 16 * * *' # Every day at 16:41 UTC (to avoid high load at exact hour values). +env: + UV_NO_SYNC: 1 + jobs: tests-full-install: name: Run tests with full install @@ -23,7 +26,7 @@ jobs: with: python-version: ${{ matrix.python-version }} - name: Install default (with full options) and test dependencies - run: uv pip install '.[full]' --group test + run: uv pip install --python-version=${{ inputs.python-version }} '.[full]' --group test - name: Run unit and doc tests with coverage report run: uv run pytest -W error tests/unit tests/doc --cov=src --cov-report=xml - name: Upload results to Codecov @@ -41,7 +44,7 @@ jobs: with: python-version: '3.13' - name: Install default (without any option) and test dependencies - run: uv pip install . --group test + run: uv pip install --python-version=${{ inputs.python-version }} . --group test - name: Run unit and doc tests with coverage report run: | uv run pytest -W error tests/unit tests/doc \ @@ -67,7 +70,7 @@ jobs: python-version: '3.13' - name: Install dependencies (default with full options & doc) - run: uv pip install '.[full]' --group doc + run: uv pip install --python-version=${{ inputs.python-version }} '.[full]' --group doc - name: Build Documentation working-directory: docs @@ -86,7 +89,7 @@ jobs: python-version: '3.13' - name: Install dependencies (default with full options & check) - run: uv pip install '.[full]' --group check + run: uv pip install --python-version=${{ inputs.python-version }} '.[full]' --group check - name: Run mypy run: uv run mypy src/torchjd diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5df922a4..1321ab8a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,21 @@ mandatory, we only provide installation steps with this tool. You can install it 2) Create a virtual environment and install the project in it. From the root of `torchjd`, run: ```bash uv venv - CC=gcc uv pip install -e '.[full]' --group check --group doc --group test --group plot + CC=gcc uv pip install --python-version=3.13.3 -e '.[full]' --group check --group doc --group test --group plot + ``` + We also advise using `UV_NO_SYNC=1` to prevent `uv` from syncing all the time. This is because by + default, it tries to resolve libraries compatible with the whole range of Python versions + supported by TorchJD, but in reality, we just need an installation compatible with the currently + used Python version. That's also why we specify `--python-version=3.14` when running + `uv pip install`. To follow that recommendation, add the following line to your `.bashrc`: + ```bash + export UV_NO_SYNC=1 + ``` + and start a new terminal. The alternative is to use the `--no-sync` flag whenever you run a pip + command that would normally sync (like `uv run`). + +3) Install pre-commit: + ```bash uv run pre-commit install ``` @@ -46,7 +60,7 @@ from the root of `torchjd`: rm -rf .venv rm uv.lock uv venv -CC=gcc uv pip install -e '.[full]' --group check --group doc --group test --group plot +CC=gcc uv pip install --python-version=3.13.3 -e '.[full]' --group check --group doc --group test --group plot uv run pre-commit install ``` From 9f29f59ea82502f7ad0ae5ba048c04bdd151078f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Val=C3=A9rian=20Rey?= Date: Wed, 29 Oct 2025 16:03:27 +0100 Subject: [PATCH 3/6] Fix python version variable in ci --- .github/workflows/build-deploy-docs.yml | 5 +++-- .github/workflows/release.yml | 5 ++++- .github/workflows/tests.yml | 15 ++++++++------- 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/.github/workflows/build-deploy-docs.yml b/.github/workflows/build-deploy-docs.yml index 0db11ae5..91c85a8b 100644 --- a/.github/workflows/build-deploy-docs.yml +++ b/.github/workflows/build-deploy-docs.yml @@ -8,6 +8,7 @@ on: env: UV_NO_SYNC: 1 + PYTHON_VERSION: 3.13 jobs: build-deploy-doc: @@ -23,10 +24,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: '3.13' + python-version: ${{ PYTHON_VERSION }} - name: Install dependencies (default with full options & doc) - run: uv pip install --python-version=${{ inputs.python-version }} '.[full]' --group doc + run: uv pip install --python-version=${{ PYTHON_VERSION }} '.[full]' --group doc - name: Determine deployment folder id: deploy_folder diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6e00a72d..7e62f88b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -4,6 +4,9 @@ on: release: types: [published] +env: + PYTHON_VERSION: 3.13 + jobs: pypi-publish: name: Publish to PyPI @@ -19,7 +22,7 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: '3.13' + python-version: ${{ PYTHON_VERSION }} - name: Build run: uv build diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9c273e94..0638ddf8 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -8,6 +8,7 @@ on: env: UV_NO_SYNC: 1 + PYTHON_VERSION: 3.13 jobs: tests-full-install: @@ -26,7 +27,7 @@ jobs: with: python-version: ${{ matrix.python-version }} - name: Install default (with full options) and test dependencies - run: uv pip install --python-version=${{ inputs.python-version }} '.[full]' --group test + run: uv pip install --python-version=${{ matrix.python-version }} '.[full]' --group test - name: Run unit and doc tests with coverage report run: uv run pytest -W error tests/unit tests/doc --cov=src --cov-report=xml - name: Upload results to Codecov @@ -42,9 +43,9 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: '3.13' + python-version: ${{ PYTHON_VERSION }} - name: Install default (without any option) and test dependencies - run: uv pip install --python-version=${{ inputs.python-version }} . --group test + run: uv pip install --python-version=${{ PYTHON_VERSION }} . --group test - name: Run unit and doc tests with coverage report run: | uv run pytest -W error tests/unit tests/doc \ @@ -67,10 +68,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: '3.13' + python-version: ${{ PYTHON_VERSION }} - name: Install dependencies (default with full options & doc) - run: uv pip install --python-version=${{ inputs.python-version }} '.[full]' --group doc + run: uv pip install --python-version=${{ PYTHON_VERSION }} '.[full]' --group doc - name: Build Documentation working-directory: docs @@ -86,10 +87,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: '3.13' + python-version: ${{ PYTHON_VERSION }} - name: Install dependencies (default with full options & check) - run: uv pip install --python-version=${{ inputs.python-version }} '.[full]' --group check + run: uv pip install --python-version=${{ PYTHON_VERSION }} '.[full]' --group check - name: Run mypy run: uv run mypy src/torchjd From 74761dccd10f72cd96c18a4233fc3a5f4fe3022b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Val=C3=A9rian=20Rey?= Date: Wed, 29 Oct 2025 16:11:29 +0100 Subject: [PATCH 4/6] Fix python version variable in ci v2 --- .github/workflows/build-deploy-docs.yml | 4 ++-- .github/workflows/release.yml | 2 +- .github/workflows/tests.yml | 12 ++++++------ 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/workflows/build-deploy-docs.yml b/.github/workflows/build-deploy-docs.yml index 91c85a8b..d5bc0f22 100644 --- a/.github/workflows/build-deploy-docs.yml +++ b/.github/workflows/build-deploy-docs.yml @@ -24,10 +24,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: ${{ PYTHON_VERSION }} + python-version: $PYTHON_VERSION - name: Install dependencies (default with full options & doc) - run: uv pip install --python-version=${{ PYTHON_VERSION }} '.[full]' --group doc + run: uv pip install --python-version=$PYTHON_VERSION '.[full]' --group doc - name: Determine deployment folder id: deploy_folder diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7e62f88b..c5e0309e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -22,7 +22,7 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: ${{ PYTHON_VERSION }} + python-version: $PYTHON_VERSION - name: Build run: uv build diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 0638ddf8..a5e88ad3 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -43,9 +43,9 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: ${{ PYTHON_VERSION }} + python-version: $PYTHON_VERSION - name: Install default (without any option) and test dependencies - run: uv pip install --python-version=${{ PYTHON_VERSION }} . --group test + run: uv pip install --python-version=$PYTHON_VERSION . --group test - name: Run unit and doc tests with coverage report run: | uv run pytest -W error tests/unit tests/doc \ @@ -68,10 +68,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: ${{ PYTHON_VERSION }} + python-version: $PYTHON_VERSION - name: Install dependencies (default with full options & doc) - run: uv pip install --python-version=${{ PYTHON_VERSION }} '.[full]' --group doc + run: uv pip install --python-version=$PYTHON_VERSION '.[full]' --group doc - name: Build Documentation working-directory: docs @@ -87,10 +87,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: ${{ PYTHON_VERSION }} + python-version: $PYTHON_VERSION - name: Install dependencies (default with full options & check) - run: uv pip install --python-version=${{ PYTHON_VERSION }} '.[full]' --group check + run: uv pip install --python-version=$PYTHON_VERSION '.[full]' --group check - name: Run mypy run: uv run mypy src/torchjd From 958ea2dac5d209b8a0e809e6ee93b918fefe0e03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Val=C3=A9rian=20Rey?= Date: Wed, 29 Oct 2025 16:12:21 +0100 Subject: [PATCH 5/6] Fix python version variable in ci v3 --- .github/workflows/build-deploy-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-deploy-docs.yml b/.github/workflows/build-deploy-docs.yml index d5bc0f22..1f2fc76d 100644 --- a/.github/workflows/build-deploy-docs.yml +++ b/.github/workflows/build-deploy-docs.yml @@ -8,7 +8,7 @@ on: env: UV_NO_SYNC: 1 - PYTHON_VERSION: 3.13 + PYTHON_VERSION: '3.13' jobs: build-deploy-doc: From 80ec3d3aa704056f9edd8a363856c809645fa3c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Val=C3=A9rian=20Rey?= Date: Wed, 29 Oct 2025 16:14:19 +0100 Subject: [PATCH 6/6] Fix python version variable in ci v4 --- .github/workflows/build-deploy-docs.yml | 4 ++-- .github/workflows/release.yml | 2 +- .github/workflows/tests.yml | 12 ++++++------ 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/workflows/build-deploy-docs.yml b/.github/workflows/build-deploy-docs.yml index 1f2fc76d..1a291f8c 100644 --- a/.github/workflows/build-deploy-docs.yml +++ b/.github/workflows/build-deploy-docs.yml @@ -24,10 +24,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: $PYTHON_VERSION + python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies (default with full options & doc) - run: uv pip install --python-version=$PYTHON_VERSION '.[full]' --group doc + run: uv pip install --python-version=${{ env.PYTHON_VERSION }} '.[full]' --group doc - name: Determine deployment folder id: deploy_folder diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c5e0309e..4744cf2f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -22,7 +22,7 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: $PYTHON_VERSION + python-version: ${{ env.PYTHON_VERSION }} - name: Build run: uv build diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a5e88ad3..5548de2f 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -43,9 +43,9 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: $PYTHON_VERSION + python-version: ${{ env.PYTHON_VERSION }} - name: Install default (without any option) and test dependencies - run: uv pip install --python-version=$PYTHON_VERSION . --group test + run: uv pip install --python-version=${{ env.PYTHON_VERSION }} . --group test - name: Run unit and doc tests with coverage report run: | uv run pytest -W error tests/unit tests/doc \ @@ -68,10 +68,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: $PYTHON_VERSION + python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies (default with full options & doc) - run: uv pip install --python-version=$PYTHON_VERSION '.[full]' --group doc + run: uv pip install --python-version=${{ env.PYTHON_VERSION }} '.[full]' --group doc - name: Build Documentation working-directory: docs @@ -87,10 +87,10 @@ jobs: - name: Set up uv uses: astral-sh/setup-uv@v5 with: - python-version: $PYTHON_VERSION + python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies (default with full options & check) - run: uv pip install --python-version=$PYTHON_VERSION '.[full]' --group check + run: uv pip install --python-version=${{ env.PYTHON_VERSION }} '.[full]' --group check - name: Run mypy run: uv run mypy src/torchjd