stepup 4.0.0rc14__tar.gz → 4.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. {stepup-4.0.0rc14 → stepup-4.0.2}/.zenodo.json +7 -5
  2. stepup-4.0.2/CITATION.cff +48 -0
  3. {stepup-4.0.0rc14 → stepup-4.0.2}/CLAUDE.md +17 -11
  4. stepup-4.0.2/CONTRIBUTING.md +44 -0
  5. {stepup-4.0.0rc14 → stepup-4.0.2}/PKG-INFO +19 -14
  6. {stepup-4.0.0rc14 → stepup-4.0.2}/README.md +4 -2
  7. {stepup-4.0.0rc14 → stepup-4.0.2}/REUSE.toml +2 -0
  8. {stepup-4.0.0rc14 → stepup-4.0.2}/pyproject.toml +40 -14
  9. stepup-4.0.2/snipwise.md +122 -0
  10. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/__init__.py +1 -1
  11. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/__main__.py +4 -2
  12. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/director.py +8 -2
  13. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/executor.py +1 -1
  14. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/render_jinja.py +7 -5
  15. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/reporter.py +2 -2
  16. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/watcher.py +1 -1
  17. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup.egg-info/PKG-INFO +19 -14
  18. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup.egg-info/SOURCES.txt +5 -2
  19. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup.egg-info/requires.txt +15 -9
  20. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup.egg-info/scm_file_list.json +9 -4
  21. stepup-4.0.2/stepup.egg-info/scm_version.json +8 -0
  22. stepup-4.0.2/tools/make_stable_redirects.py +119 -0
  23. stepup-4.0.0rc14/.claude/skills/release/SKILL.md +0 -18
  24. stepup-4.0.0rc14/stepup.egg-info/scm_version.json +0 -8
  25. {stepup-4.0.0rc14 → stepup-4.0.2}/LICENSE +0 -0
  26. {stepup-4.0.0rc14 → stepup-4.0.2}/LICENSES/CC-BY-SA-4.0.txt +0 -0
  27. {stepup-4.0.0rc14 → stepup-4.0.2}/LICENSES/LGPL-3.0-or-later.txt +0 -0
  28. {stepup-4.0.0rc14 → stepup-4.0.2}/LICENSES/LicenseRef-StepUp-Logo-v1.txt +0 -0
  29. {stepup-4.0.0rc14 → stepup-4.0.2}/MANIFEST.in +0 -0
  30. {stepup-4.0.0rc14 → stepup-4.0.2}/setup.cfg +0 -0
  31. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/CLAUDE.md +0 -0
  32. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/api.py +0 -0
  33. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/asyncio.py +0 -0
  34. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/browse.py +0 -0
  35. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/builder.py +0 -0
  36. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/call.py +0 -0
  37. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/cattrs.py +0 -0
  38. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/cgroups.py +0 -0
  39. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/clean.py +0 -0
  40. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/config_loader.py +0 -0
  41. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/config_tool.py +0 -0
  42. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/constants.py +0 -0
  43. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/enums.py +0 -0
  44. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/exceptions.py +0 -0
  45. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/extapi.py +0 -0
  46. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/file.py +0 -0
  47. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/finalize.py +0 -0
  48. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/hash.py +0 -0
  49. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/hash_queue.py +0 -0
  50. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/interact.py +0 -0
  51. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/job.py +0 -0
  52. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/logo.svg +0 -0
  53. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/nglob.py +0 -0
  54. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/outcome.py +0 -0
  55. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/path.py +0 -0
  56. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/pending.py +0 -0
  57. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/pytest.py +0 -0
  58. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/rpc.py +0 -0
  59. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/run.py +0 -0
  60. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/scheduler.py +0 -0
  61. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/script.py +0 -0
  62. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/sqlite3.py +0 -0
  63. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/startup.py +0 -0
  64. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/static_tree.py +0 -0
  65. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/status.py +0 -0
  66. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/step.py +0 -0
  67. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/stepinfo.py +0 -0
  68. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/tool.py +0 -0
  69. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/tracebacks.py +0 -0
  70. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/trellis.py +0 -0
  71. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/tui.py +0 -0
  72. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/usage.py +0 -0
  73. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/utils.py +0 -0
  74. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup/core/workflow.py +0 -0
  75. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup.egg-info/dependency_links.txt +0 -0
  76. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup.egg-info/entry_points.txt +0 -0
  77. {stepup-4.0.0rc14 → stepup-4.0.2}/stepup.egg-info/top_level.txt +0 -0
  78. {stepup-4.0.0rc14 → stepup-4.0.2}/tools/.gitignore +0 -0
  79. {stepup-4.0.0rc14 → stepup-4.0.2}/tools/analyze_perf.py +0 -0
  80. {stepup-4.0.0rc14 → stepup-4.0.2}/tools/leaves.py +0 -0
@@ -19,17 +19,19 @@
19
19
  "language": "eng",
20
20
  "keywords": [
21
21
  "asyncio",
22
- "build tool",
23
22
  "build automation",
24
- "workflow management",
23
+ "build tool",
25
24
  "dynamic dependencies",
26
25
  "incremental build",
27
- "reproducible research",
26
+ "parallel",
27
+ "POSIX",
28
+ "Python",
28
29
  "reproducibility",
30
+ "reproducible research",
31
+ "StepUp",
29
32
  "terminal application",
30
33
  "workflow",
31
- "POSIX",
32
- "Python"
34
+ "workflow management"
33
35
  ],
34
36
  "related_identifiers": [
35
37
  {
@@ -0,0 +1,48 @@
1
+ # SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
2
+ # SPDX-License-Identifier: LGPL-3.0-or-later
3
+ cff-version: 1.2.0
4
+ message: If you use this software, please cite it using these metadata.
5
+ title: StepUp Core
6
+ type: software
7
+ url: https://reproducible-reporting.github.io/stepup-core
8
+ abstract: >-
9
+ StepUp is a dynamic build tool and a modern alternative to
10
+ Make.
11
+ Its defining feature is that workflow generation and execution are unified:
12
+ a plan.py script defines the initial build steps.
13
+ While the workflow is being executed, any step can add more steps and dependencies,
14
+ based on the outputs built so far.
15
+ This makes StepUp ideal for builds
16
+ where the full set of dependencies cannot be determined in advance.
17
+ authors:
18
+ - family-names: Verstraelen
19
+ given-names: Toon
20
+ orcid: https://orcid.org/0000-0001-9288-5608
21
+ affiliation: Center for Molecular Modeling (CMM), Ghent University
22
+ address: Technologiepark-Zwijnaarde 46
23
+ post-code: 9052
24
+ city: Zwijnaarde
25
+ country: BE
26
+ license: LGPL-3.0-or-later
27
+ repository-code: https://github.com/reproducible-reporting/stepup-core
28
+ keywords:
29
+ # snipwise.md BEGIN keywords
30
+ - asyncio
31
+ - build automation
32
+ - build tool
33
+ - dynamic dependencies
34
+ - incremental build
35
+ - parallel
36
+ - POSIX
37
+ - Python
38
+ - reproducibility
39
+ - reproducible research
40
+ - StepUp
41
+ - terminal application
42
+ - workflow
43
+ - workflow management
44
+ # snipwise.md END keywords
45
+ identifiers:
46
+ - type: doi
47
+ value: 10.5281/zenodo.22018869
48
+ description: Concept DOI, which always resolves to the latest archived version.
@@ -19,7 +19,7 @@ Guidance that applies to only part of the repo lives next to the code it governs
19
19
 
20
20
  - `stepup/core/CLAUDE.md`: process model, workflow-graph invariants, database conventions.
21
21
  - `tests/CLAUDE.md`: test layout and the integration-example suite.
22
- - `docs/CLAUDE.md`: regenerating the tutorial output.
22
+ - `docs/CLAUDE.md`: regenerating the tutorial output and social card.
23
23
  - `.claude/skills/release/SKILL.md`: the release procedure.
24
24
 
25
25
  ## Non-Negotiables
@@ -63,16 +63,22 @@ The following test command completes quickly as it skips the integration tests:
63
63
  pytest -k "not test_example"
64
64
  ```
65
65
 
66
- Always wrap the quick test run in a short timeout, e.g.:
67
-
68
- ```bash
69
- timeout 15 pytest -k "not test_example"
70
- ```
71
-
72
- 15 seconds is very generous for this selection.
73
- If a step crashes, the `client` test fixture can otherwise block indefinitely
74
- (it waits for the workflow to reach a state that never arrives),
75
- so a timeout prevents a runaway, hanging test process.
66
+ Every test is bounded by `pytest-timeout`, configured in `pyproject.toml`.
67
+ Setup, call and teardown of one test share a budget of 15 seconds,
68
+ which is very generous for this selection.
69
+ Without it, a test can hang forever instead of failing,
70
+ because the asynchronous RPC client takes no timeout
71
+ and the director waits for its steps without a deadline.
72
+ `tests/test_interrupt.py` and `tests/test_examples.py` raise the budget with a
73
+ module-level `timeout` marker, because their tests police their own deadlines.
74
+ Keep those markers above the deadline the module enforces itself,
75
+ so that a failure is reported by the assertion that knows what went wrong.
76
+
77
+ The budget is not a complete safety net.
78
+ `pytest-timeout` cancels the timer of a test as soon as pytest reports a failure,
79
+ which leaves the teardown of a test whose setup failed entirely unguarded.
80
+ A fixture that waits for a subprocess must therefore bound that wait itself,
81
+ as the `client` fixture does with `SHUTDOWN_TIMEOUT`.
76
82
 
77
83
  It may also be useful to run a small number of integration tests,
78
84
  to get a first quick feedback on the overall system:
@@ -0,0 +1,44 @@
1
+ <!--
2
+ SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
3
+ SPDX-License-Identifier: CC-BY-SA-4.0
4
+ -->
5
+
6
+ # Contributing to StepUp Core
7
+
8
+ Contributions are welcome, from bug reports and documentation fixes to new features.
9
+
10
+ ## Reporting Bugs and Requesting Features
11
+
12
+ Open an [issue](https://github.com/reproducible-reporting/stepup-core/issues).
13
+ For a bug, please include the StepUp version, the Python version, the operating system,
14
+ and a minimal example that reproduces the problem.
15
+
16
+ ## Setting up a Development Environment
17
+
18
+ The [developer notes](https://reproducible-reporting.github.io/stepup-core/development/)
19
+ explain how to install the development environment with
20
+ [uv](https://docs.astral.sh/uv/) and [pre-commit](https://pre-commit.com/),
21
+ how to run the tests, and how to build the documentation locally.
22
+
23
+ ## Making Changes
24
+
25
+ - Discuss larger changes in an issue before you start working on them,
26
+ so that you do not invest time in an approach that turns out not to fit.
27
+ - Install the pre-commit hooks with `pre-commit install`.
28
+ They format and lint every commit,
29
+ and the same checks run in continuous integration.
30
+ - Add tests for the behaviour you change, and make sure `pytest` passes.
31
+ - Wrap English text with [Semantic Line Breaks](https://sembr.org/),
32
+ because it keeps the diffs of prose small.
33
+ - Add an entry to `docs/changelog.md` when your change is visible to users.
34
+
35
+ ## Pull Requests
36
+
37
+ Open a pull request against the `main` branch
38
+ and describe what the change does and why it is needed.
39
+ The general conventions of the Reproducible Reporting organization are documented in
40
+ the [organization contributing guide](https://github.com/reproducible-reporting/.github/blob/main/CONTRIBUTING.md).
41
+
42
+ By contributing, you agree that your contributions are licensed under the
43
+ [LGPL-3.0-or-later](https://github.com/reproducible-reporting/stepup-core/blob/main/LICENSE)
44
+ license.
@@ -1,14 +1,15 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: stepup
3
- Version: 4.0.0rc14
4
- Summary: StepUp Core provides the basic framework for the StepUp build tool
3
+ Version: 4.0.2
4
+ Summary: A dynamic Python build tool for reproducible workflows
5
5
  Author-email: Toon Verstraelen <toon.verstraelen@ugent.be>
6
6
  License-Expression: LGPL-3.0-or-later
7
7
  Project-URL: Documentation, https://reproducible-reporting.github.io/stepup-core/
8
8
  Project-URL: Issues, https://github.com/reproducible-reporting/stepup-core/issues
9
9
  Project-URL: Source, https://github.com/reproducible-reporting/stepup-core/
10
10
  Project-URL: Changelog, https://reproducible-reporting.github.io/stepup-core/changelog/
11
- Classifier: Development Status :: 4 - Beta
11
+ Keywords: asyncio,build automation,build tool,dynamic dependencies,incremental build,parallel,POSIX,Python,reproducibility,reproducible research,StepUp,terminal application,workflow,workflow management
12
+ Classifier: Development Status :: 5 - Production/Stable
12
13
  Classifier: Environment :: Console
13
14
  Classifier: Intended Audience :: Education
14
15
  Classifier: Intended Audience :: Science/Research
@@ -24,7 +25,7 @@ Classifier: Topic :: Software Development :: Build Tools
24
25
  Requires-Python: >=3.11
25
26
  Description-Content-Type: text/markdown
26
27
  License-File: LICENSE
27
- Requires-Dist: asyncinotify>=4.0.9
28
+ Requires-Dist: asyncinotify>=4.0.9; sys_platform == "linux"
28
29
  Requires-Dist: attrs>=23.1.0
29
30
  Requires-Dist: cattrs>=23.2.3
30
31
  Requires-Dist: jinja2>=3.1.6
@@ -32,20 +33,22 @@ Requires-Dist: parse>=1.19.1
32
33
  Requires-Dist: path>=16.14.0
33
34
  Requires-Dist: pyyaml>=6.0
34
35
  Requires-Dist: rich>=13.0.0
36
+ Provides-Extra: tests
37
+ Requires-Dist: pytest>=8.2.0; extra == "tests"
38
+ Requires-Dist: pytest-asyncio>=0.24; extra == "tests"
39
+ Requires-Dist: pytest-timeout>=2.3.1; extra == "tests"
40
+ Requires-Dist: pytest-xdist>=3.6.1; extra == "tests"
41
+ Provides-Extra: examples
42
+ Requires-Dist: matplotlib>=3.8.0; extra == "examples"
43
+ Requires-Dist: numpy>=1.26.0; extra == "examples"
35
44
  Provides-Extra: dev
36
- Requires-Dist: cffconvert; extra == "dev"
37
- Requires-Dist: matplotlib; extra == "dev"
38
- Requires-Dist: mike; extra == "dev"
45
+ Requires-Dist: stepup[examples,tests]; extra == "dev"
39
46
  Requires-Dist: mkdocs; extra == "dev"
40
47
  Requires-Dist: mkdocstrings[python]; extra == "dev"
41
48
  Requires-Dist: mkdocs-macros-plugin; extra == "dev"
42
49
  Requires-Dist: mkdocs-material; extra == "dev"
43
- Requires-Dist: numpy; extra == "dev"
44
- Requires-Dist: pytest; extra == "dev"
45
- Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
46
- Requires-Dist: pytest-xdist; extra == "dev"
47
- Requires-Dist: psutil; extra == "dev"
48
50
  Requires-Dist: reuse; extra == "dev"
51
+ Requires-Dist: snipwise<2.0a0; extra == "dev"
49
52
  Requires-Dist: yappi; extra == "dev"
50
53
  Dynamic: license-file
51
54
 
@@ -65,6 +68,7 @@ SPDX-License-Identifier: LGPL-3.0-or-later
65
68
  ![LGPL-3 License](https://img.shields.io/badge/License-LGPL_v3-blue.svg)
66
69
  [![CodeFactor](https://www.codefactor.io/repository/github/reproducible-reporting/stepup-core/badge)](https://www.codefactor.io/repository/github/reproducible-reporting/stepup-core)
67
70
 
71
+ <!-- snipwise.md BEGIN abstract -->
68
72
  StepUp is a dynamic build tool and a modern alternative to
69
73
  [Make](https://en.wikipedia.org/wiki/Make_(software)).
70
74
  Its defining feature is that workflow generation and execution are unified:
@@ -73,6 +77,7 @@ While the workflow is being executed, any step can add more steps and dependenci
73
77
  based on the outputs built so far.
74
78
  This makes StepUp ideal for builds
75
79
  where the full set of dependencies cannot be determined in advance.
80
+ <!-- snipwise.md END abstract -->
76
81
 
77
82
  StepUp Core provides the basic framework for StepUp, without any domain-specific features.
78
83
  Those live in extension packages:
@@ -93,7 +98,7 @@ for details.
93
98
 
94
99
  ## Quick Visual Impression
95
100
 
96
- [![asciicast](https://asciinema.org/a/718833.svg)](https://asciinema.org/a/718833)
101
+ [![asciicast](https://asciinema.org/a/pJXDBvCXT9ndHDuo.svg)](https://asciinema.org/a/pJXDBvCXT9ndHDuo)
97
102
 
98
103
  ## Documentation
99
104
 
@@ -103,7 +108,7 @@ is available at <https://reproducible-reporting.github.io/stepup-core>.
103
108
  ## License
104
109
 
105
110
  StepUp Core is distributed under the terms of the
106
- [LGPL-3.0-or-later](LICENSE) license.
111
+ [LGPL-3.0-or-later](https://github.com/reproducible-reporting/stepup-core/blob/main/LICENSE) license.
107
112
  Contributions are welcome;
108
113
  see the [development guide](https://reproducible-reporting.github.io/stepup-core/development/)
109
114
  to get started.
@@ -14,6 +14,7 @@ SPDX-License-Identifier: LGPL-3.0-or-later
14
14
  ![LGPL-3 License](https://img.shields.io/badge/License-LGPL_v3-blue.svg)
15
15
  [![CodeFactor](https://www.codefactor.io/repository/github/reproducible-reporting/stepup-core/badge)](https://www.codefactor.io/repository/github/reproducible-reporting/stepup-core)
16
16
 
17
+ <!-- snipwise.md BEGIN abstract -->
17
18
  StepUp is a dynamic build tool and a modern alternative to
18
19
  [Make](https://en.wikipedia.org/wiki/Make_(software)).
19
20
  Its defining feature is that workflow generation and execution are unified:
@@ -22,6 +23,7 @@ While the workflow is being executed, any step can add more steps and dependenci
22
23
  based on the outputs built so far.
23
24
  This makes StepUp ideal for builds
24
25
  where the full set of dependencies cannot be determined in advance.
26
+ <!-- snipwise.md END abstract -->
25
27
 
26
28
  StepUp Core provides the basic framework for StepUp, without any domain-specific features.
27
29
  Those live in extension packages:
@@ -42,7 +44,7 @@ for details.
42
44
 
43
45
  ## Quick Visual Impression
44
46
 
45
- [![asciicast](https://asciinema.org/a/718833.svg)](https://asciinema.org/a/718833)
47
+ [![asciicast](https://asciinema.org/a/pJXDBvCXT9ndHDuo.svg)](https://asciinema.org/a/pJXDBvCXT9ndHDuo)
46
48
 
47
49
  ## Documentation
48
50
 
@@ -52,7 +54,7 @@ is available at <https://reproducible-reporting.github.io/stepup-core>.
52
54
  ## License
53
55
 
54
56
  StepUp Core is distributed under the terms of the
55
- [LGPL-3.0-or-later](LICENSE) license.
57
+ [LGPL-3.0-or-later](https://github.com/reproducible-reporting/stepup-core/blob/main/LICENSE) license.
56
58
  Contributions are welcome;
57
59
  see the [development guide](https://reproducible-reporting.github.io/stepup-core/development/)
58
60
  to get started.
@@ -39,6 +39,8 @@ SPDX-License-Identifier = "LGPL-3.0-or-later"
39
39
  [[annotations]]
40
40
  path = [
41
41
  "docs/logo.svg",
42
+ "docs/social-card.jpg",
43
+ "docs/social-card.svg",
42
44
  "stepup/core/logo.svg",
43
45
  ]
44
46
  SPDX-FileCopyrightText = "2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>"
@@ -1,7 +1,7 @@
1
1
  # SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
2
2
  # SPDX-License-Identifier: LGPL-3.0-or-later
3
3
  [build-system]
4
- requires = ["setuptools>=65.0", "setuptools_scm>=8.1"]
4
+ requires = ["setuptools>=77.0", "setuptools_scm>=8.1"]
5
5
  build-backend = "setuptools.build_meta"
6
6
 
7
7
  [project]
@@ -9,12 +9,30 @@ name = "stepup"
9
9
  authors = [
10
10
  { name="Toon Verstraelen", email="toon.verstraelen@ugent.be" },
11
11
  ]
12
- description = "StepUp Core provides the basic framework for the StepUp build tool"
12
+ description = "A dynamic Python build tool for reproducible workflows"
13
13
  readme = "README.md"
14
14
  license = "LGPL-3.0-or-later"
15
15
  requires-python = ">=3.11"
16
+ keywords = [
17
+ # snipwise.md BEGIN keywords
18
+ "asyncio",
19
+ "build automation",
20
+ "build tool",
21
+ "dynamic dependencies",
22
+ "incremental build",
23
+ "parallel",
24
+ "POSIX",
25
+ "Python",
26
+ "reproducibility",
27
+ "reproducible research",
28
+ "StepUp",
29
+ "terminal application",
30
+ "workflow",
31
+ "workflow management",
32
+ # snipwise.md END keywords
33
+ ]
16
34
  classifiers = [
17
- "Development Status :: 4 - Beta",
35
+ "Development Status :: 5 - Production/Stable",
18
36
  "Environment :: Console",
19
37
  "Intended Audience :: Education",
20
38
  "Intended Audience :: Science/Research",
@@ -29,8 +47,7 @@ classifiers = [
29
47
  "Topic :: Software Development :: Build Tools",
30
48
  ]
31
49
  dependencies = [
32
- # Ensure changes to these dependencies are reflected in .github/requirements-old.txt
33
- "asyncinotify>=4.0.9",
50
+ "asyncinotify>=4.0.9 ; sys_platform == 'linux'",
34
51
  "attrs>=23.1.0",
35
52
  "cattrs>=23.2.3",
36
53
  "jinja2>=3.1.6",
@@ -42,20 +59,29 @@ dependencies = [
42
59
  dynamic = ["version"]
43
60
 
44
61
  [project.optional-dependencies]
62
+ # What the test suite needs, and nothing more.
63
+ # The pytest workflow installs this extra rather than `dev`,
64
+ # because it resolves the oldest supported versions of the direct dependencies,
65
+ # which is only meaningful for packages that the tests actually exercise.
66
+ tests = [
67
+ "pytest>=8.2.0",
68
+ "pytest-asyncio>=0.24",
69
+ "pytest-timeout>=2.3.1",
70
+ "pytest-xdist>=3.6.1",
71
+ ]
72
+ # What the documentation examples need, which the smoke workflow runs.
73
+ examples = [
74
+ "matplotlib>=3.8.0",
75
+ "numpy>=1.26.0",
76
+ ]
45
77
  dev = [
46
- "cffconvert",
47
- "matplotlib",
48
- "mike",
78
+ "stepup[tests,examples]",
49
79
  "mkdocs",
50
80
  "mkdocstrings[python]",
51
81
  "mkdocs-macros-plugin",
52
82
  "mkdocs-material",
53
- "numpy",
54
- "pytest",
55
- "pytest-asyncio>=0.24",
56
- "pytest-xdist",
57
- "psutil",
58
83
  "reuse",
84
+ "snipwise<2.0a0",
59
85
  "yappi",
60
86
  ]
61
87
 
@@ -84,7 +110,6 @@ config = "stepup.core.config_tool:add_config_subcommand"
84
110
  shutdown = "stepup.core.interact:add_shutdown_subcommand"
85
111
  status = "stepup.core.status:add_status_subcommand"
86
112
 
87
-
88
113
  [tool.pytest.ini_options]
89
114
  addopts = "-n auto --dist worksteal -W error -W ignore::ResourceWarning"
90
115
  asyncio_mode = "auto"
@@ -92,6 +117,7 @@ asyncio_default_fixture_loop_scope = "function"
92
117
  markers = [
93
118
  "requires_forkserver: mark test that requires STEPUP_BUILD_FORKSERVER != 0",
94
119
  ]
120
+ timeout = 15
95
121
 
96
122
  [tool.ruff]
97
123
  line-length = 100
@@ -0,0 +1,122 @@
1
+ <!--
2
+ SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
3
+ SPDX-License-Identifier: LGPL-3.0-or-later
4
+ -->
5
+
6
+ # Snipwise Configuration
7
+
8
+ Consult the full documentation at <https://reproducible-reporting.github.io/snipwise/>.
9
+
10
+ ```toml
11
+ # The Markdown files show the abstract as it is written below, links and all.
12
+ [[targets]]
13
+ patterns = ["README.md", "docs/index.md"]
14
+
15
+ # The summary of the Python package metadata, which is a single-line TOML string.
16
+ [[targets]]
17
+ patterns = ["pyproject.toml"]
18
+ scanner = "regex"
19
+ regex = '(?m)^description = "(?P<content>[^"]*)"$'
20
+ snippets = ["tagline"]
21
+ render = "{{ content | unwrap }}"
22
+
23
+ # The meta description that every documentation page carries.
24
+ [[targets]]
25
+ patterns = ["mkdocs.yaml"]
26
+ scanner = "regex"
27
+ regex = '(?m)^site_description: (?P<content>.*)$'
28
+ snippets = ["tagline"]
29
+ render = "{{ content | unwrap }}"
30
+
31
+ # The docstring of the package, which is a single-line string.
32
+ [[targets]]
33
+ patterns = ["stepup/core/__init__.py"]
34
+ scanner = "regex"
35
+ regex = '(?m)^"""(?P<content>[^"]*)"""$'
36
+ snippets = ["tagline"]
37
+ render = "{{ content | unwrap | suffix('.') }}"
38
+
39
+ # The CLI description.
40
+ [[targets]]
41
+ patterns = ["stepup/core/__main__.py"]
42
+ scanner = "regex"
43
+ regex = '(?m)^\s*description="(?P<content>[^"]*)\\n\\n"$'
44
+ snippets = ["tagline"]
45
+ render = "{{ content | unwrap | suffix('.') }}"
46
+
47
+ # The tagline in the social card, whose tspan carries the id that locates it.
48
+ [[targets]]
49
+ patterns = ["docs/social-card.svg"]
50
+ scanner = "regex"
51
+ regex = '<tspan\b[^>]*\bid="tagline"[^>]*>(?P<content>[^<]*)</tspan>'
52
+ snippets = ["tagline"]
53
+ render = "{{ content | unwrap }}"
54
+
55
+ # The keywords array of the Python package metadata.
56
+ [[targets]]
57
+ patterns = ["pyproject.toml"]
58
+ snippets = ["keywords"]
59
+ render = '''{{ content | prefix('"') | suffix('",') }}'''
60
+
61
+ # The abstract of the citation metadata, which is a folded YAML block scalar.
62
+ # The template terminates the last line, because the region includes its newline.
63
+ [[targets]]
64
+ patterns = ["CITATION.cff"]
65
+ scanner = "regex"
66
+ regex = '(?m)^abstract: >-\n(?P<content>(?:^ .*\n)+)'
67
+ snippets = ["abstract"]
68
+ render = "{{ content | plain | prefix(' ') }}\n"
69
+
70
+ # The keywords sequence of the citation metadata.
71
+ [[targets]]
72
+ patterns = ["CITATION.cff"]
73
+ snippets = ["keywords"]
74
+ render = "{{ content | prefix('- ') }}"
75
+
76
+ # The Zenodo metadata, which is JSON and therefore carries no markers.
77
+ [[targets]]
78
+ patterns = [".zenodo.json"]
79
+ scanner = "json"
80
+ insert = [
81
+ { snippet = "abstract", pointer = "/description", render = "{{ content | plain | unwrap }}" },
82
+ { snippet = "keywords", pointer = "/keywords", shape = "lines" },
83
+ ]
84
+ ```
85
+
86
+ ## `tagline`
87
+
88
+ ```text
89
+ A dynamic Python build tool for reproducible workflows
90
+ ```
91
+
92
+ ## `abstract`
93
+
94
+ ```markdown
95
+ StepUp is a dynamic build tool and a modern alternative to
96
+ [Make](https://en.wikipedia.org/wiki/Make_(software)).
97
+ Its defining feature is that workflow generation and execution are unified:
98
+ a `plan.py` script defines the initial build steps.
99
+ While the workflow is being executed, any step can add more steps and dependencies,
100
+ based on the outputs built so far.
101
+ This makes StepUp ideal for builds
102
+ where the full set of dependencies cannot be determined in advance.
103
+ ```
104
+
105
+ ## `keywords`
106
+
107
+ ```text
108
+ asyncio
109
+ build automation
110
+ build tool
111
+ dynamic dependencies
112
+ incremental build
113
+ parallel
114
+ POSIX
115
+ Python
116
+ reproducibility
117
+ reproducible research
118
+ StepUp
119
+ terminal application
120
+ workflow
121
+ workflow management
122
+ ```
@@ -1,5 +1,5 @@
1
1
  # SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
2
2
  # SPDX-License-Identifier: LGPL-3.0-or-later
3
- """StepUp Core package."""
3
+ """A dynamic Python build tool for reproducible workflows."""
4
4
 
5
5
  __all__ = ()
@@ -110,7 +110,9 @@ def _setup_cli() -> tuple[argparse.ArgumentParser, ConfigLoader]:
110
110
  # Base argument parser
111
111
  parser = argparse.ArgumentParser(
112
112
  prog="stepup",
113
- description="General purpose dynamic build tool.",
113
+ formatter_class=argparse.RawDescriptionHelpFormatter,
114
+ description="A dynamic Python build tool for reproducible workflows.\n\n"
115
+ "Documentation: https://reproducible-reporting.github.io/stepup-core/",
114
116
  )
115
117
  version = get_version("stepup")
116
118
  parser.add_argument("-V", "--version", action="version", version="%(prog)s " + version)
@@ -151,4 +153,4 @@ def _exit_on_config_problems(loader: ConfigLoader) -> None:
151
153
 
152
154
 
153
155
  if __name__ == "__main__":
154
- main()
156
+ sys.exit(main())
@@ -728,7 +728,13 @@ async def watch_first_loop(watcher: Watcher, handler: "DirectorHandler", stop_ev
728
728
  """Run pending steps 0.5 seconds after the watcher observes a file change."""
729
729
  with watcher.subscribe_changes() as changed_event:
730
730
  while True:
731
- await watcher.busy_watching.wait()
731
+ # Every wait below must also watch `stop_event`,
732
+ # because the director shuts down only after this loop has ended.
733
+ # Once the shutdown has begun, the watch phase never starts again,
734
+ # so waiting for it alone would block the shutdown forever.
735
+ await wait_for_any_event(watcher.busy_watching, stop_event)
736
+ if stop_event.is_set():
737
+ break
732
738
  await wait_for_any_event(changed_event, stop_event)
733
739
  if stop_event.is_set():
734
740
  break
@@ -1281,4 +1287,4 @@ class DirectorHandler:
1281
1287
 
1282
1288
 
1283
1289
  if __name__ == "__main__":
1284
- main()
1290
+ sys.exit(main())
@@ -954,4 +954,4 @@ class Executor:
954
954
  pages = [("Outdated dynamic dependencies", page_change)]
955
955
  if len(page_same) > 0:
956
956
  pages.append(("Remained the same (or missing)", page_same))
957
- await self.reporter("DROPAMEND", run.description, pages)
957
+ await self.reporter("UNAMEND", run.description, pages)
@@ -8,6 +8,8 @@ and may be complemented with a JSON string on the command line.
8
8
 
9
9
  import argparse
10
10
  import json
11
+ import sys
12
+ from collections.abc import Sequence
11
13
  from typing import Any
12
14
 
13
15
  import jinja2
@@ -21,9 +23,9 @@ from .path import StrPath, coerce_str
21
23
  __all__ = ("main", "render_jinja_file", "render_jinja_str")
22
24
 
23
25
 
24
- def main() -> None:
26
+ def main(argv: Sequence[str] | None = None) -> None:
25
27
  """Command-line entry point for the `render-jinja` console script."""
26
- args = _parse_args()
28
+ args = _parse_args(argv)
27
29
  latex = _resolve_latex(args.mode, args.path_out)
28
30
  dir_out = args.path_out.parent.absolute()
29
31
  variables = vars(loadns(*args.paths_variables, dir_out=dir_out, do_amend=False))
@@ -38,7 +40,7 @@ def main() -> None:
38
40
  args.path_out.chmod(args.path_in.stat().st_mode)
39
41
 
40
42
 
41
- def _parse_args() -> argparse.Namespace:
43
+ def _parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
42
44
  """Parse the command line arguments of the `render-jinja` console script."""
43
45
  parser = argparse.ArgumentParser(
44
46
  prog="sc-render-jinja",
@@ -66,7 +68,7 @@ def _parse_args() -> argparse.Namespace:
66
68
  "--json",
67
69
  help="Variables are given as a JSON string (overrules the variables defined in files)",
68
70
  )
69
- return parser.parse_args()
71
+ return parser.parse_args(argv)
70
72
 
71
73
 
72
74
  def _resolve_latex(mode: str, path_out: StrPath) -> bool:
@@ -153,4 +155,4 @@ def render_jinja_str(
153
155
 
154
156
 
155
157
  if __name__ == "__main__":
156
- main()
158
+ sys.exit(main())
@@ -41,12 +41,12 @@ TAG_COLORS = {
41
41
  "SUCCESS": "green",
42
42
  # Workflow-related details
43
43
  "DELETED": "cyan",
44
- "DROPAMEND": "cyan",
44
+ "UNAMEND": "cyan",
45
45
  "NOSKIP": "cyan",
46
46
  "DEFERRED": "cyan",
47
47
  "REMOVE": "cyan",
48
48
  "SKIP": "cyan",
49
- "UNCHANGED": "cyan",
49
+ "SAMEHASH": "cyan",
50
50
  "UPDATED": "cyan",
51
51
  # Events outside the workflow
52
52
  "DIRECTOR": "magenta",
@@ -221,7 +221,7 @@ class Watcher:
221
221
  # so its round trips are made after the transaction closes,
222
222
  # instead of holding the database write lock for the duration of the network traffic.
223
223
  for path in dropped:
224
- await self.reporter("UNCHANGED", path)
224
+ await self.reporter("SAMEHASH", path)
225
225
 
226
226
  # Reset the watcher state.
227
227
  # The subscriber events are cleared together with the sets they refer to,
@@ -1,14 +1,15 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: stepup
3
- Version: 4.0.0rc14
4
- Summary: StepUp Core provides the basic framework for the StepUp build tool
3
+ Version: 4.0.2
4
+ Summary: A dynamic Python build tool for reproducible workflows
5
5
  Author-email: Toon Verstraelen <toon.verstraelen@ugent.be>
6
6
  License-Expression: LGPL-3.0-or-later
7
7
  Project-URL: Documentation, https://reproducible-reporting.github.io/stepup-core/
8
8
  Project-URL: Issues, https://github.com/reproducible-reporting/stepup-core/issues
9
9
  Project-URL: Source, https://github.com/reproducible-reporting/stepup-core/
10
10
  Project-URL: Changelog, https://reproducible-reporting.github.io/stepup-core/changelog/
11
- Classifier: Development Status :: 4 - Beta
11
+ Keywords: asyncio,build automation,build tool,dynamic dependencies,incremental build,parallel,POSIX,Python,reproducibility,reproducible research,StepUp,terminal application,workflow,workflow management
12
+ Classifier: Development Status :: 5 - Production/Stable
12
13
  Classifier: Environment :: Console
13
14
  Classifier: Intended Audience :: Education
14
15
  Classifier: Intended Audience :: Science/Research
@@ -24,7 +25,7 @@ Classifier: Topic :: Software Development :: Build Tools
24
25
  Requires-Python: >=3.11
25
26
  Description-Content-Type: text/markdown
26
27
  License-File: LICENSE
27
- Requires-Dist: asyncinotify>=4.0.9
28
+ Requires-Dist: asyncinotify>=4.0.9; sys_platform == "linux"
28
29
  Requires-Dist: attrs>=23.1.0
29
30
  Requires-Dist: cattrs>=23.2.3
30
31
  Requires-Dist: jinja2>=3.1.6
@@ -32,20 +33,22 @@ Requires-Dist: parse>=1.19.1
32
33
  Requires-Dist: path>=16.14.0
33
34
  Requires-Dist: pyyaml>=6.0
34
35
  Requires-Dist: rich>=13.0.0
36
+ Provides-Extra: tests
37
+ Requires-Dist: pytest>=8.2.0; extra == "tests"
38
+ Requires-Dist: pytest-asyncio>=0.24; extra == "tests"
39
+ Requires-Dist: pytest-timeout>=2.3.1; extra == "tests"
40
+ Requires-Dist: pytest-xdist>=3.6.1; extra == "tests"
41
+ Provides-Extra: examples
42
+ Requires-Dist: matplotlib>=3.8.0; extra == "examples"
43
+ Requires-Dist: numpy>=1.26.0; extra == "examples"
35
44
  Provides-Extra: dev
36
- Requires-Dist: cffconvert; extra == "dev"
37
- Requires-Dist: matplotlib; extra == "dev"
38
- Requires-Dist: mike; extra == "dev"
45
+ Requires-Dist: stepup[examples,tests]; extra == "dev"
39
46
  Requires-Dist: mkdocs; extra == "dev"
40
47
  Requires-Dist: mkdocstrings[python]; extra == "dev"
41
48
  Requires-Dist: mkdocs-macros-plugin; extra == "dev"
42
49
  Requires-Dist: mkdocs-material; extra == "dev"
43
- Requires-Dist: numpy; extra == "dev"
44
- Requires-Dist: pytest; extra == "dev"
45
- Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
46
- Requires-Dist: pytest-xdist; extra == "dev"
47
- Requires-Dist: psutil; extra == "dev"
48
50
  Requires-Dist: reuse; extra == "dev"
51
+ Requires-Dist: snipwise<2.0a0; extra == "dev"
49
52
  Requires-Dist: yappi; extra == "dev"
50
53
  Dynamic: license-file
51
54
 
@@ -65,6 +68,7 @@ SPDX-License-Identifier: LGPL-3.0-or-later
65
68
  ![LGPL-3 License](https://img.shields.io/badge/License-LGPL_v3-blue.svg)
66
69
  [![CodeFactor](https://www.codefactor.io/repository/github/reproducible-reporting/stepup-core/badge)](https://www.codefactor.io/repository/github/reproducible-reporting/stepup-core)
67
70
 
71
+ <!-- snipwise.md BEGIN abstract -->
68
72
  StepUp is a dynamic build tool and a modern alternative to
69
73
  [Make](https://en.wikipedia.org/wiki/Make_(software)).
70
74
  Its defining feature is that workflow generation and execution are unified:
@@ -73,6 +77,7 @@ While the workflow is being executed, any step can add more steps and dependenci
73
77
  based on the outputs built so far.
74
78
  This makes StepUp ideal for builds
75
79
  where the full set of dependencies cannot be determined in advance.
80
+ <!-- snipwise.md END abstract -->
76
81
 
77
82
  StepUp Core provides the basic framework for StepUp, without any domain-specific features.
78
83
  Those live in extension packages:
@@ -93,7 +98,7 @@ for details.
93
98
 
94
99
  ## Quick Visual Impression
95
100
 
96
- [![asciicast](https://asciinema.org/a/718833.svg)](https://asciinema.org/a/718833)
101
+ [![asciicast](https://asciinema.org/a/pJXDBvCXT9ndHDuo.svg)](https://asciinema.org/a/pJXDBvCXT9ndHDuo)
97
102
 
98
103
  ## Documentation
99
104
 
@@ -103,7 +108,7 @@ is available at <https://reproducible-reporting.github.io/stepup-core>.
103
108
  ## License
104
109
 
105
110
  StepUp Core is distributed under the terms of the
106
- [LGPL-3.0-or-later](LICENSE) license.
111
+ [LGPL-3.0-or-later](https://github.com/reproducible-reporting/stepup-core/blob/main/LICENSE) license.
107
112
  Contributions are welcome;
108
113
  see the [development guide](https://reproducible-reporting.github.io/stepup-core/development/)
109
114
  to get started.
@@ -1,11 +1,13 @@
1
1
  .zenodo.json
2
+ CITATION.cff
2
3
  CLAUDE.md
4
+ CONTRIBUTING.md
3
5
  LICENSE
4
6
  MANIFEST.in
5
7
  README.md
6
8
  REUSE.toml
7
9
  pyproject.toml
8
- .claude/skills/release/SKILL.md
10
+ snipwise.md
9
11
  LICENSES/CC-BY-SA-4.0.txt
10
12
  LICENSES/LGPL-3.0-or-later.txt
11
13
  LICENSES/LicenseRef-StepUp-Logo-v1.txt
@@ -70,4 +72,5 @@ stepup/core/watcher.py
70
72
  stepup/core/workflow.py
71
73
  tools/.gitignore
72
74
  tools/analyze_perf.py
73
- tools/leaves.py
75
+ tools/leaves.py
76
+ tools/make_stable_redirects.py
@@ -1,4 +1,3 @@
1
- asyncinotify>=4.0.9
2
1
  attrs>=23.1.0
3
2
  cattrs>=23.2.3
4
3
  jinja2>=3.1.6
@@ -7,18 +6,25 @@ path>=16.14.0
7
6
  pyyaml>=6.0
8
7
  rich>=13.0.0
9
8
 
9
+ [:sys_platform == "linux"]
10
+ asyncinotify>=4.0.9
11
+
10
12
  [dev]
11
- cffconvert
12
- matplotlib
13
- mike
13
+ stepup[examples,tests]
14
14
  mkdocs
15
15
  mkdocstrings[python]
16
16
  mkdocs-macros-plugin
17
17
  mkdocs-material
18
- numpy
19
- pytest
20
- pytest-asyncio>=0.24
21
- pytest-xdist
22
- psutil
23
18
  reuse
19
+ snipwise<2.0a0
24
20
  yappi
21
+
22
+ [examples]
23
+ matplotlib>=3.8.0
24
+ numpy>=1.26.0
25
+
26
+ [tests]
27
+ pytest>=8.2.0
28
+ pytest-asyncio>=0.24
29
+ pytest-timeout>=2.3.1
30
+ pytest-xdist>=3.6.1
@@ -1,9 +1,7 @@
1
1
  {
2
2
  "files": [
3
- ".claude/skills/release/SKILL.md",
4
3
  ".editorconfig",
5
- ".github/requirements-old.txt",
6
- ".github/scripts/extract-notes.sh",
4
+ ".github/extract-notes.sh",
7
5
  ".github/workflows/mkdocs.yaml",
8
6
  ".github/workflows/pytest.yaml",
9
7
  ".github/workflows/release.yaml",
@@ -11,7 +9,9 @@
11
9
  ".gitignore",
12
10
  ".pre-commit-config.yaml",
13
11
  ".zenodo.json",
12
+ "CITATION.cff",
14
13
  "CLAUDE.md",
14
+ "CONTRIBUTING.md",
15
15
  "LICENSE",
16
16
  "LICENSES/CC-BY-SA-4.0.txt",
17
17
  "LICENSES/LGPL-3.0-or-later.txt",
@@ -282,9 +282,13 @@
282
282
  "docs/reference/stepup.core.render_jinja.md",
283
283
  "docs/reference/stepup.core.stepinfo.md",
284
284
  "docs/run_example.py",
285
+ "docs/social-card.jpg",
286
+ "docs/social-card.svg",
285
287
  "mkdocs.yaml",
288
+ "overrides/404.html",
286
289
  "overrides/main.html",
287
290
  "pyproject.toml",
291
+ "snipwise.md",
288
292
  "stepup/core/CLAUDE.md",
289
293
  "stepup/core/__init__.py",
290
294
  "stepup/core/__main__.py",
@@ -2890,6 +2894,7 @@
2890
2894
  "tests/test_workflow.py",
2891
2895
  "tools/.gitignore",
2892
2896
  "tools/analyze_perf.py",
2893
- "tools/leaves.py"
2897
+ "tools/leaves.py",
2898
+ "tools/make_stable_redirects.py"
2894
2899
  ]
2895
2900
  }
@@ -0,0 +1,8 @@
1
+ {
2
+ "tag": "4.0.2",
3
+ "distance": 0,
4
+ "node": "g1d6cf4159b77d58e5778392dea41636480c84451",
5
+ "dirty": false,
6
+ "branch": "HEAD",
7
+ "node_date": "2026-09-18"
8
+ }
@@ -0,0 +1,119 @@
1
+ #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
3
+ # SPDX-License-Identifier: LGPL-3.0-or-later
4
+ """Write redirects from the retired `stable/` URL space to the flat documentation site.
5
+
6
+ Up to StepUp 3.2, the documentation was published per version with `mike`,
7
+ and `stable/` was the alias that readers and search engines were pointed to.
8
+ The site is now published flat, so every `stable/...` URL would return a 404.
9
+
10
+ `overrides/404.html` already rewrites such URLs in the browser,
11
+ but GitHub Pages serves that page with an HTTP 404 status,
12
+ which tells search engines to drop the old URL instead of following it.
13
+ The stubs written here are served with an HTTP 200 status
14
+ and carry both a canonical link and an instant meta refresh,
15
+ which search engines do treat as a redirect that passes ranking signals.
16
+
17
+ Usage
18
+ -----
19
+ ```bash
20
+ mkdocs build --strict
21
+ python tools/make_stable_redirects.py site
22
+ ```
23
+
24
+ When These Redirects Can Be Removed
25
+ -----------------------------------
26
+ They exist only to hand the ranking of the old `stable/` URLs to their flat counterparts.
27
+ Remove them once Google Search Console reports no impressions
28
+ on `stable/` URLs for several consecutive months,
29
+ and the flat URLs are indexed in their place.
30
+ Google advises keeping a redirect in place for at least a year,
31
+ so the earliest sensible moment to revisit this is one year after the first flat deployment.
32
+
33
+ Removal is a soft landing rather than a cliff:
34
+ `overrides/404.html` keeps rewriting `stable/` URLs afterwards,
35
+ so readers still reach the right page,
36
+ and only the transfer of ranking signals is lost.
37
+ """
38
+
39
+ import sys
40
+ from pathlib import Path
41
+ from xml.etree import ElementTree as ET
42
+
43
+ SITEMAP_NS = {"sm": "http://www.sitemaps.org/schemas/sitemap/0.9"}
44
+
45
+ REDIRECT_TEMPLATE = """<!DOCTYPE html>
46
+ <html lang="en">
47
+ <head>
48
+ <meta charset="utf-8">
49
+ <title>Redirecting to {target}</title>
50
+ <link rel="canonical" href="{target}">
51
+ <meta http-equiv="refresh" content="0; url={target}">
52
+ </head>
53
+ <body>
54
+ <p>This page has moved to <a href="{target}">{target}</a>.</p>
55
+ </body>
56
+ </html>
57
+ """
58
+
59
+
60
+ def read_page_urls(sitemap_path: Path) -> list[str]:
61
+ """Collect the page URLs from a sitemap written by MkDocs.
62
+
63
+ Parameters
64
+ ----------
65
+ sitemap_path
66
+ The `sitemap.xml` in the root of a built site.
67
+
68
+ Returns
69
+ -------
70
+ urls
71
+ The page URLs, sorted, with the home page first.
72
+ """
73
+ root = ET.parse(sitemap_path).getroot()
74
+ urls = [element.text.strip() for element in root.iterfind("sm:url/sm:loc", SITEMAP_NS)]
75
+ if not urls:
76
+ raise ValueError(f"No URLs found in {sitemap_path}")
77
+ return sorted(urls, key=len)
78
+
79
+
80
+ def write_redirects(site_dir: Path) -> int:
81
+ """Write a redirect stub under `stable/` for every page of a built site.
82
+
83
+ Parameters
84
+ ----------
85
+ site_dir
86
+ The output directory of `mkdocs build`.
87
+
88
+ Returns
89
+ -------
90
+ count
91
+ The number of stubs written.
92
+ """
93
+ urls = read_page_urls(site_dir / "sitemap.xml")
94
+ # The home page is the shortest URL and is the prefix of all the others.
95
+ home = urls[0]
96
+ count = 0
97
+ for url in urls:
98
+ if not url.startswith(home):
99
+ raise ValueError(f"URL {url} does not start with the home page URL {home}")
100
+ relative = url[len(home) :]
101
+ destination = site_dir / "stable" / relative / "index.html"
102
+ destination.parent.mkdir(parents=True, exist_ok=True)
103
+ destination.write_text(REDIRECT_TEMPLATE.format(target=url))
104
+ count += 1
105
+ return count
106
+
107
+
108
+ def main() -> None:
109
+ """Command line interface."""
110
+ if len(sys.argv) != 2:
111
+ print(__doc__)
112
+ raise SystemExit(2)
113
+ site_dir = Path(sys.argv[1])
114
+ count = write_redirects(site_dir)
115
+ print(f"Wrote {count} redirect stubs under {site_dir / 'stable'}")
116
+
117
+
118
+ if __name__ == "__main__":
119
+ main()
@@ -1,18 +0,0 @@
1
- ---
2
- name: release
3
- description: >-
4
- Release procedure for StepUp Core: update the changelog, tag the version,
5
- and push so the PyPI GitHub Action fires.
6
- Use when cutting a release, tagging a version, or publishing to PyPI.
7
- ---
8
-
9
- <!--
10
- SPDX-FileCopyrightText: 2024 Toon Verstraelen <Toon.Verstraelen@UGent.be>
11
- SPDX-License-Identifier: LGPL-3.0-or-later
12
- -->
13
-
14
- # Release Process
15
-
16
- 1. Update `docs/changelog.md`.
17
- 2. Commit and tag: `git tag vX.Y.Z`.
18
- 3. Push with tags: `git push origin main --tags`, which triggers the PyPI GitHub Action.
@@ -1,8 +0,0 @@
1
- {
2
- "tag": "4.0.0rc14",
3
- "distance": 0,
4
- "node": "g41e198b64a3a90b34be32886ad8a3cc87e6ea410",
5
- "dirty": false,
6
- "branch": "HEAD",
7
- "node_date": "2026-08-25"
8
- }
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes