Add requirements-reference.txt by PranjalManhgaye · Pull Request #871 · precice/tutorials

PranjalManhgaye · 2026-07-09T05:27:59Z

Summary

This PR implements #610 using the approach discussed after #749 and it is the rework of that:

Tutorial requirements.txt files keep loose version ranges (for example numpy >1, <2, pyprecice~=3.0). This PR fills gaps where develop still had unpinned packages (~~39 files; ~ ~13 already had ranges).
A new root file requirements-reference.txt records the exact PyPI versions that satisfy those ranges at generation time (Gemfile.lock style).
tools/report_tutorial_requirements.py generates and checks that file from PyPI.
CI workflow check-requirements-reference.yml runs --check when requirements or the script change.
Tutorial run.sh scripts are unchanged and still install from local requirements.txt. The reference file is for reproducibility and releases, not for day-to-day installs.

This is not tied to reference_versions.yaml and does not change tools/tests/requirements.txt (CI git refs are already handled by #857/#858).

Test Plan

python3 tools/report_tutorial_requirements.py
python3 tools/report_tutorial_requirements.py --check
pre-commit run actionlint --files .github/workflows/check-requirements-reference.yml
pip install --dry-run -r elastic-tube-1d/fluid-python/requirements.txt

Closes #610

Add loose version constraints to remaining tutorial requirements.txt files, generate requirements-reference.txt from PyPI, and check it in CI.

Remove extra trailing blank line in the Python dependencies section.

MakisH

Thank you for the contribution; this will be useful, and it comes at the right time.

My main suggestion, which will change a bit the code, is to split the requirements-reference.txt into one file per requirements.txt.

Other than that, most comments are regarding the version ranges. We do not need to document these in detail, but the comments here might be helpful in the future.

MakisH · 2026-07-09T19:04:35Z

+    # Not a pip requirements file (lists stdlib os, unpinned vtk); see develop naming quirk.
+    "flow-over-heated-plate/plot-final-interface-temperature-requirements.txt",


This should actually be a requirements.txt file. I wanted to tidy these plotting python scripts a bit.

Useful to have an exclusion list, I guess (mainly for unmaintained tutorials), but why does this need to be excluded?

Done, moved to plot-final-interface-temperature/requirements.txt (dropped invalid OS), and removed the special exclusion.

Good point, but the script itself should also be in that directory then.

You can also make a directory utils/: https://precice.org/community-contribute-to-precice.html#structure-of-a-tutorial

…ependency-versions-clean

Move the generator to tools/releasing/, emit sibling reference files instead of a root manifest, and clean up requirements from review feedback.

MakisH

The version ranges look fine. The system tests pass: https://github.com/precice/tutorials/actions/runs/29193941172?pr=871

I had a closer look at the script, here are some more comments.

MakisH · 2026-07-12T13:18:00Z

+from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
+from packaging.utils import canonicalize_name
+from packaging.version import Version


It looks like we also need a requirements.txt for this tool.

MakisH · 2026-07-12T13:26:57Z

+Run from the repository root:
+  python3 tools/releasing/report_tutorial_requirements.py
+  python3 tools/releasing/report_tutorial_requirements.py --check


Some suggestions for the interface:

I would name it update-requirements-reference.py: dashes for consistency with most of our tools (yes, we can improve that), clearly point to these files.

It would be nice to accept a path to only update files in that directory. In the PR template, you added a step to do that, but one can only update all files at once.

By default, all files will be updated, because the date/time is always different. This makes it difficult to see which of them actually changed in terms of versions. An option --all would be mostly intuitive to me (any better ideas?).

MakisH · 2026-07-12T13:29:33Z

+        if outdated:
+            print("ERROR: outdated requirements-reference.txt files:", file=sys.stderr)
+            for path in outdated:
+                print(f"  - {path}", file=sys.stderr)
+        print(
+            "Run: python3 tools/releasing/report_tutorial_requirements.py",
+            file=sys.stderr,
+        )
+        return 1
+


I think that the outdated ones should only give a warning, not an error. We should only update them when making a new release.

MakisH · 2026-07-12T13:31:53Z

+  push:
+    branches:
+      - master
+      - develop
+    paths:
+      - '**/requirements.txt'
+      - '**/requirements-reference.txt'
+      - tools/releasing/report_tutorial_requirements.py
+  pull_request:
+    branches:
+      - master
+      - develop
+    paths:
+      - '**/requirements.txt'
+      - '**/requirements-reference.txt'
+      - tools/releasing/report_tutorial_requirements.py


I think that we should check:

In a PR to develop: That there are requirements-reference.txt files: The first time a tutorial is added, it would be good to archive that information.

In a PR to master (i.e., a release): That the requirements-reference.txt files are up to date: This is the time I would expect them to be updated.

I would say that the push event is not needed, then.

MakisH · 2026-07-12T13:34:29Z

+    # Not a pip requirements file (lists stdlib os, unpinned vtk); see develop naming quirk.
+    "flow-over-heated-plate/plot-final-interface-temperature-requirements.txt",


Good point, but the script itself should also be in that directory then.

You can also make a directory utils/: https://precice.org/community-contribute-to-precice.html#structure-of-a-tutorial

MakisH · 2026-07-12T13:36:13Z

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""
+Report resolved Python dependency versions for tutorial requirements.txt files.


Not sure if you only mean the files corresponding to tutorials cases, but I think we should cover every requirements.txt file in this repository. There is a list with exceptions, which is nice, but I think it should be empty by default, unless there is a good reason not to.

MakisH · 2026-07-12T13:39:34Z

+
+def parse_requirement_line(line: str) -> str | None:
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#") or stripped.startswith("--"):


What is the -- for?

PranjalManhgaye added 3 commits July 9, 2026 09:05

Add tutorial Python dependency reference manifest for precice#610

6e583b7

Add loose version constraints to remaining tutorial requirements.txt files, generate requirements-reference.txt from PyPI, and check it in CI.

Update 610.md

626dd48

Fix markdownlint MD012 in README.md

f08a2cb

Remove extra trailing blank line in the Python dependencies section.

PranjalManhgaye requested a review from MakisH July 9, 2026 05:36

PranjalManhgaye added this to GSoC 2026: System tests improvements Jul 9, 2026

github-project-automation Bot moved this to Planned next in GSoC 2026: System tests improvements Jul 9, 2026

PranjalManhgaye moved this from Planned next to Needs review in GSoC 2026: System tests improvements Jul 9, 2026

PranjalManhgaye changed the title ~~Add tutorial Python dependency reference manifest for #610~~ Add tutorial Python dependency reference manifest (rework of #749, closes #610) Jul 9, 2026

PranjalManhgaye changed the title ~~Add tutorial Python dependency reference manifest (rework of #749, closes #610)~~ Add tutorial Python dependency reference manifest (rework of #749) Jul 9, 2026

MakisH reviewed Jul 9, 2026

View reviewed changes

MakisH changed the title ~~Add tutorial Python dependency reference manifest (rework of #749)~~ Add requirements-reference.txt Jul 9, 2026

PranjalManhgaye added 2 commits July 10, 2026 16:49

Merge remote-tracking branch 'upstream/develop' into fix-610-python-d…

bd584b7

…ependency-versions-clean

Address precice#871 review: per-participant requirements-reference files

6b5e773

Move the generator to tools/releasing/, emit sibling reference files instead of a root manifest, and clean up requirements from review feedback.

PranjalManhgaye requested a review from MakisH July 10, 2026 17:06

Merge branch 'develop' into fix-610-python-dependency-versions-clean

2a89e82

MakisH added the trigger-system-tests label Jul 12, 2026

Merge branch 'develop' into fix-610-python-dependency-versions-clean

1b5b921

MakisH added trigger-system-tests and removed trigger-system-tests labels Jul 12, 2026

MakisH reviewed Jul 12, 2026

View reviewed changes

		# Not a pip requirements file (lists stdlib os, unpinned vtk); see develop naming quirk.
		"flow-over-heated-plate/plot-final-interface-temperature-requirements.txt",

Uh oh!

Uh oh!

Conversation

PranjalManhgaye commented Jul 9, 2026

Summary

Test Plan

Uh oh!

MakisH left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MakisH left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MakisH left a comment •

edited

Loading