stepup-queue 2.0.0rc4__tar.gz → 2.0.1__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 (32) hide show
  1. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/.zenodo.json +15 -11
  2. stepup_queue-2.0.1/CITATION.cff +68 -0
  3. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/CLAUDE.md +6 -4
  4. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/PKG-INFO +15 -11
  5. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/README.md +4 -2
  6. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/REUSE.toml +5 -1
  7. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/pyproject.toml +47 -14
  8. stepup_queue-2.0.1/snipwise.md +118 -0
  9. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup/queue/CLAUDE.md +11 -0
  10. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup/queue/__init__.py +1 -1
  11. stepup_queue-2.0.0rc4/stepup/queue/canceljobs.py → stepup_queue-2.0.1/stepup/queue/cancel_jobs.py +19 -18
  12. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup/queue/log.py +40 -8
  13. stepup_queue-2.0.0rc4/stepup/queue/removejobs.py → stepup_queue-2.0.1/stepup/queue/remove_jobs.py +33 -14
  14. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup/queue/sbatch.py +150 -44
  15. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup/queue/utils.py +3 -2
  16. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup_queue.egg-info/PKG-INFO +15 -11
  17. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup_queue.egg-info/SOURCES.txt +4 -2
  18. stepup_queue-2.0.1/stepup_queue.egg-info/entry_points.txt +4 -0
  19. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup_queue.egg-info/requires.txt +9 -7
  20. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup_queue.egg-info/scm_file_list.json +11 -4
  21. stepup_queue-2.0.1/stepup_queue.egg-info/scm_version.json +8 -0
  22. stepup_queue-2.0.0rc4/stepup_queue.egg-info/entry_points.txt +0 -6
  23. stepup_queue-2.0.0rc4/stepup_queue.egg-info/scm_version.json +0 -8
  24. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/LICENSE +0 -0
  25. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/LICENSES/CC-BY-SA-4.0.txt +0 -0
  26. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/LICENSES/LGPL-3.0-or-later.txt +0 -0
  27. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/LICENSES/LicenseRef-StepUp-Logo-v1.txt +0 -0
  28. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/MANIFEST.in +0 -0
  29. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/setup.cfg +0 -0
  30. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup/queue/api.py +0 -0
  31. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup_queue.egg-info/dependency_links.txt +0 -0
  32. {stepup_queue-2.0.0rc4 → stepup_queue-2.0.1}/stepup_queue.egg-info/top_level.txt +0 -0
@@ -18,24 +18,28 @@
18
18
  ],
19
19
  "language": "eng",
20
20
  "keywords": [
21
- "SLURM",
21
+ "asyncio",
22
+ "batch computing",
23
+ "build automation",
24
+ "build tool",
25
+ "extension",
26
+ "high-performance computing",
27
+ "HPC",
22
28
  "job scheduler",
23
29
  "job submission",
30
+ "parallel",
31
+ "POSIX",
32
+ "Python",
24
33
  "queued jobs",
25
- "batch computing",
26
- "high-performance computing",
27
- "supercomputer",
28
- "workflow automation",
29
- "workflow management",
30
- "build tool",
31
- "build automation",
32
34
  "reproducibility",
33
35
  "reproducible research",
34
36
  "research software",
35
- "extension",
37
+ "SLURM",
38
+ "StepUp",
36
39
  "StepUp Core",
37
- "POSIX",
38
- "Python"
40
+ "supercomputer",
41
+ "workflow automation",
42
+ "workflow management"
39
43
  ],
40
44
  "related_identifiers": [
41
45
  {
@@ -0,0 +1,68 @@
1
+ # SPDX-FileCopyrightText: 2025 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 Queue
6
+ type: software
7
+ url: https://reproducible-reporting.github.io/stepup-queue
8
+ abstract: >-
9
+ StepUp Queue is an experimental StepUp
10
+ extension to integrate queued jobs into a workflow.
11
+ It currently supports integration with SLURM
12
+ and is designed to be extensible to other job schedulers.
13
+ authors:
14
+ - family-names: Verstraelen
15
+ given-names: Toon
16
+ orcid: https://orcid.org/0000-0001-9288-5608
17
+ affiliation: Center for Molecular Modeling (CMM), Ghent University
18
+ address: Technologiepark-Zwijnaarde 46
19
+ post-code: 9052
20
+ city: Zwijnaarde
21
+ country: BE
22
+ license: LGPL-3.0-or-later
23
+ repository-code: https://github.com/reproducible-reporting/stepup-queue
24
+ keywords:
25
+ # snipwise.md BEGIN keywords
26
+ - asyncio
27
+ - batch computing
28
+ - build automation
29
+ - build tool
30
+ - extension
31
+ - high-performance computing
32
+ - HPC
33
+ - job scheduler
34
+ - job submission
35
+ - parallel
36
+ - POSIX
37
+ - Python
38
+ - queued jobs
39
+ - reproducibility
40
+ - reproducible research
41
+ - research software
42
+ - SLURM
43
+ - StepUp
44
+ - StepUp Core
45
+ - supercomputer
46
+ - workflow automation
47
+ - workflow management
48
+ # snipwise.md END keywords
49
+ identifiers:
50
+ - type: doi
51
+ value: 10.5281/zenodo.22024209
52
+ description: Concept DOI, which always resolves to the latest archived version.
53
+ references:
54
+ - title: StepUp Core
55
+ type: software
56
+ authors:
57
+ - family-names: Verstraelen
58
+ given-names: Toon
59
+ orcid: https://orcid.org/0000-0001-9288-5608
60
+ affiliation: Center for Molecular Modeling (CMM), Ghent University
61
+ url: https://reproducible-reporting.github.io/stepup-core
62
+ repository-code: https://github.com/reproducible-reporting/stepup-core
63
+ license: LGPL-3.0-or-later
64
+ identifiers:
65
+ - type: doi
66
+ value: 10.5281/zenodo.22018869
67
+ description: Concept DOI, which always resolves to the latest archived version.
68
+ notes: StepUp Queue is an extension of StepUp Core and requires it at runtime.
@@ -12,6 +12,7 @@ Guidance that applies to only part of the repo lives next to the code it governs
12
12
 
13
13
  - `stepup/queue/CLAUDE.md`: job file conventions, the submit-and-wait contract, sacct caching.
14
14
  - `tests/CLAUDE.md`: test layout and conventions.
15
+ - `docs/CLAUDE.md`: regenerating the social card.
15
16
 
16
17
  ## Project Overview
17
18
 
@@ -31,10 +32,11 @@ The package is organized around two layers:
31
32
  Its `sbatch()` function calls `stepup.core.api.run()`
32
33
  to register a `sq-sbatch-and-wait` step with StepUp Core.
33
34
 
34
- - **Individual command modules** each implement a `main()` function that serves as a CLI tool.
35
- These are registered via `[project.scripts]` and the `stepup.tools` entry points
36
- in `pyproject.toml`, and are invoked by StepUp steps as external commands.
37
- When StepUp executes such a step, the command runs in the working directory of the job.
35
+ - **Individual command modules** each implement a function that serves as a CLI entry point.
36
+ These are registered via `[project.scripts]` in `pyproject.toml`.
37
+ `sq-sbatch-and-wait` is invoked by StepUp steps as an external command,
38
+ and runs in the working directory of the job.
39
+ `sq-cancel-jobs` and `sq-remove-jobs` are run by the user from the shell.
38
40
 
39
41
  ## Coding Conventions
40
42
 
@@ -1,13 +1,14 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: stepup-queue
3
- Version: 2.0.0rc4
4
- Summary: StepUp Queue integrates queued jobs into a StepUp workflow.
3
+ Version: 2.0.1
4
+ Summary: Integrate SLURM jobs into a StepUp workflow
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-queue/
8
8
  Project-URL: Issues, https://github.com/reproducible-reporting/stepup-queue/issues
9
9
  Project-URL: Source, https://github.com/reproducible-reporting/stepup-queue/
10
10
  Project-URL: Changelog, https://reproducible-reporting.github.io/stepup-queue/changelog/
11
+ Keywords: asyncio,batch computing,build automation,build tool,extension,high-performance computing,HPC,job scheduler,job submission,parallel,POSIX,Python,queued jobs,reproducibility,reproducible research,research software,SLURM,StepUp,StepUp Core,supercomputer,workflow automation,workflow management
11
12
  Classifier: Development Status :: 4 - Beta
12
13
  Classifier: Environment :: Console
13
14
  Classifier: Intended Audience :: Education
@@ -26,19 +27,20 @@ Description-Content-Type: text/markdown
26
27
  License-File: LICENSE
27
28
  Requires-Dist: path>=16.14.0
28
29
  Requires-Dist: rich>=13.0.0
29
- Requires-Dist: stepup<5.0.0a1,>=4.0.0rc12
30
+ Requires-Dist: stepup<5.0.0a1,>=4.0.3
31
+ Provides-Extra: tests
32
+ Requires-Dist: pytest>=8.2.0; extra == "tests"
33
+ Requires-Dist: pytest-asyncio>=0.24; extra == "tests"
34
+ Requires-Dist: pytest-timeout>=2.3.1; extra == "tests"
35
+ Requires-Dist: pytest-xdist>=3.6.1; extra == "tests"
30
36
  Provides-Extra: dev
31
- Requires-Dist: cffconvert; extra == "dev"
32
- Requires-Dist: mike; extra == "dev"
37
+ Requires-Dist: stepup-queue[tests]; extra == "dev"
33
38
  Requires-Dist: mkdocs; extra == "dev"
34
39
  Requires-Dist: mkdocstrings[python]; extra == "dev"
35
40
  Requires-Dist: mkdocs-macros-plugin; extra == "dev"
36
41
  Requires-Dist: mkdocs-material; extra == "dev"
37
- Requires-Dist: psutil; extra == "dev"
38
- Requires-Dist: pytest; extra == "dev"
39
- Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
40
- Requires-Dist: pytest-xdist; extra == "dev"
41
42
  Requires-Dist: reuse; extra == "dev"
43
+ Requires-Dist: snipwise<2.0a0; extra == "dev"
42
44
  Dynamic: license-file
43
45
 
44
46
  <!--
@@ -56,9 +58,11 @@ SPDX-License-Identifier: LGPL-3.0-or-later
56
58
  ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/stepup-queue)
57
59
  ![LGPL-3 License](https://img.shields.io/badge/License-LGPL_v3-blue.svg)
58
60
 
61
+ <!-- snipwise.md BEGIN abstract -->
59
62
  StepUp Queue is an experimental [StepUp](https://reproducible-reporting.github.io/stepup-core)
60
63
  extension to integrate queued jobs into a workflow.
61
- Currently, it only supports integration with [SLURM](https://slurm.schedmd.com/),
62
- but it is designed to be extensible to other job schedulers.
64
+ It currently supports integration with [SLURM](https://slurm.schedmd.com/)
65
+ and is designed to be extensible to other job schedulers.
66
+ <!-- snipwise.md END abstract -->
63
67
 
64
68
  For more information, consult the [documentation](https://reproducible-reporting.github.io/stepup-queue).
@@ -13,9 +13,11 @@ SPDX-License-Identifier: LGPL-3.0-or-later
13
13
  ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/stepup-queue)
14
14
  ![LGPL-3 License](https://img.shields.io/badge/License-LGPL_v3-blue.svg)
15
15
 
16
+ <!-- snipwise.md BEGIN abstract -->
16
17
  StepUp Queue is an experimental [StepUp](https://reproducible-reporting.github.io/stepup-core)
17
18
  extension to integrate queued jobs into a workflow.
18
- Currently, it only supports integration with [SLURM](https://slurm.schedmd.com/),
19
- but it is designed to be extensible to other job schedulers.
19
+ It currently supports integration with [SLURM](https://slurm.schedmd.com/)
20
+ and is designed to be extensible to other job schedulers.
21
+ <!-- snipwise.md END abstract -->
20
22
 
21
23
  For more information, consult the [documentation](https://reproducible-reporting.github.io/stepup-queue).
@@ -20,6 +20,10 @@ SPDX-FileCopyrightText = "2025 Toon Verstraelen <Toon.Verstraelen@UGent.be>"
20
20
  SPDX-License-Identifier = "LGPL-3.0-or-later"
21
21
 
22
22
  [[annotations]]
23
- path = "docs/logo.svg"
23
+ path = [
24
+ "docs/logo.svg",
25
+ "docs/social-card.jpg",
26
+ "docs/social-card.svg",
27
+ ]
24
28
  SPDX-FileCopyrightText = "2025 Toon Verstraelen <Toon.Verstraelen@UGent.be>"
25
29
  SPDX-License-Identifier = "LicenseRef-StepUp-Logo-v1"
@@ -1,7 +1,7 @@
1
1
  # SPDX-FileCopyrightText: 2025 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,10 +9,36 @@ name = "stepup-queue"
9
9
  authors = [
10
10
  { name="Toon Verstraelen", email="toon.verstraelen@ugent.be" },
11
11
  ]
12
- description = "StepUp Queue integrates queued jobs into a StepUp workflow."
12
+ description = "Integrate SLURM jobs into a StepUp workflow"
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
+ "batch computing",
20
+ "build automation",
21
+ "build tool",
22
+ "extension",
23
+ "high-performance computing",
24
+ "HPC",
25
+ "job scheduler",
26
+ "job submission",
27
+ "parallel",
28
+ "POSIX",
29
+ "Python",
30
+ "queued jobs",
31
+ "reproducibility",
32
+ "reproducible research",
33
+ "research software",
34
+ "SLURM",
35
+ "StepUp",
36
+ "StepUp Core",
37
+ "supercomputer",
38
+ "workflow automation",
39
+ "workflow management",
40
+ # snipwise.md END keywords
41
+ ]
16
42
  classifiers = [
17
43
  "Development Status :: 4 - Beta",
18
44
  "Environment :: Console",
@@ -29,26 +55,31 @@ classifiers = [
29
55
  "Topic :: Software Development :: Build Tools",
30
56
  ]
31
57
  dependencies = [
32
- # Ensure changes to these dependencies are reflected in .github/requirements-old.txt
33
58
  "path>=16.14.0",
34
59
  "rich>=13.0.0",
35
- "stepup>=4.0.0rc12,<5.0.0a1",
60
+ "stepup>=4.0.3,<5.0.0a1",
36
61
  ]
37
62
  dynamic = ["version"]
38
63
 
39
64
  [project.optional-dependencies]
65
+ # What the test suite needs, and nothing more.
66
+ # The pytest workflow installs this extra rather than `dev`,
67
+ # because it resolves the oldest supported versions of the direct dependencies,
68
+ # which is only meaningful for packages that the tests actually exercise.
69
+ tests = [
70
+ "pytest>=8.2.0",
71
+ "pytest-asyncio>=0.24",
72
+ "pytest-timeout>=2.3.1",
73
+ "pytest-xdist>=3.6.1",
74
+ ]
40
75
  dev = [
41
- "cffconvert",
42
- "mike",
76
+ "stepup-queue[tests]",
43
77
  "mkdocs",
44
78
  "mkdocstrings[python]",
45
79
  "mkdocs-macros-plugin",
46
80
  "mkdocs-material",
47
- "psutil",
48
- "pytest",
49
- "pytest-asyncio>=0.24",
50
- "pytest-xdist",
51
81
  "reuse",
82
+ "snipwise<2.0a0",
52
83
  ]
53
84
 
54
85
  [project.urls]
@@ -58,15 +89,14 @@ Source = "https://github.com/reproducible-reporting/stepup-queue/"
58
89
  Changelog = "https://reproducible-reporting.github.io/stepup-queue/changelog/"
59
90
 
60
91
  [project.scripts]
92
+ sq-cancel-jobs = "stepup.queue.cancel_jobs:cancel_jobs"
93
+ sq-remove-jobs = "stepup.queue.remove_jobs:remove_jobs"
61
94
  sq-sbatch-and-wait = "stepup.queue.sbatch:sbatch"
62
95
 
63
- [project.entry-points."stepup.tools"]
64
- canceljobs = "stepup.queue.canceljobs:canceljobs_subcommand"
65
- removejobs = "stepup.queue.removejobs:removejobs_subcommand"
66
-
67
96
  [tool.pytest.ini_options]
68
97
  addopts = "-n auto --dist worksteal -W error -W ignore::ResourceWarning"
69
98
  asyncio_default_fixture_loop_scope = "function"
99
+ timeout = 15
70
100
 
71
101
  [tool.ruff]
72
102
  line-length = 100
@@ -109,6 +139,9 @@ local_scheme = "no-local-version"
109
139
  [tool.pymarkdown]
110
140
  # Report unknown or mistyped settings instead of silently ignoring them.
111
141
  mode.strict-config = true
142
+ # The documentation pages carry YAML front matter,
143
+ # which pymarkdown parses as a setext heading unless this extension is on.
144
+ extensions.front-matter.enabled = true
112
145
  # The documentation indents nested lists by four spaces, matching Python-Markdown and MkDocs.
113
146
  plugins.md007.indent = 4
114
147
  plugins.md013.line_length = 100
@@ -0,0 +1,118 @@
1
+ <!--
2
+ SPDX-FileCopyrightText: 2025 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/queue/__init__.py"]
34
+ scanner = "regex"
35
+ regex = '(?m)^"""(?P<content>[^"]*)"""$'
36
+ snippets = ["tagline"]
37
+ render = "{{ content | unwrap | suffix('.') }}"
38
+
39
+ # The tagline in the social card, whose tspan carries the id that locates it.
40
+ [[targets]]
41
+ patterns = ["docs/social-card.svg"]
42
+ scanner = "regex"
43
+ regex = '<tspan\b[^>]*\bid="tagline"[^>]*>(?P<content>[^<]*)</tspan>'
44
+ snippets = ["tagline"]
45
+ render = "{{ content | unwrap }}"
46
+
47
+ # The keywords array of the Python package metadata.
48
+ [[targets]]
49
+ patterns = ["pyproject.toml"]
50
+ snippets = ["keywords"]
51
+ render = '''{{ content | prefix('"') | suffix('",') }}'''
52
+
53
+ # The abstract of the citation metadata, which is a folded YAML block scalar.
54
+ # The template terminates the last line, because the region includes its newline.
55
+ [[targets]]
56
+ patterns = ["CITATION.cff"]
57
+ scanner = "regex"
58
+ regex = '(?m)^abstract: >-\n(?P<content>(?:^ .*\n)+)'
59
+ snippets = ["abstract"]
60
+ render = "{{ content | plain | prefix(' ') }}\n"
61
+
62
+ # The keywords sequence of the citation metadata.
63
+ [[targets]]
64
+ patterns = ["CITATION.cff"]
65
+ snippets = ["keywords"]
66
+ render = "{{ content | prefix('- ') }}"
67
+
68
+ # The Zenodo metadata, which is JSON and therefore carries no markers.
69
+ [[targets]]
70
+ patterns = [".zenodo.json"]
71
+ scanner = "json"
72
+ insert = [
73
+ { snippet = "abstract", pointer = "/description", render = "{{ content | plain | unwrap }}" },
74
+ { snippet = "keywords", pointer = "/keywords", shape = "lines" },
75
+ ]
76
+ ```
77
+
78
+ ## `tagline`
79
+
80
+ ```text
81
+ Integrate SLURM jobs into a StepUp workflow
82
+ ```
83
+
84
+ ## `abstract`
85
+
86
+ ```markdown
87
+ StepUp Queue is an experimental [StepUp](https://reproducible-reporting.github.io/stepup-core)
88
+ extension to integrate queued jobs into a workflow.
89
+ It currently supports integration with [SLURM](https://slurm.schedmd.com/)
90
+ and is designed to be extensible to other job schedulers.
91
+ ```
92
+
93
+ ## `keywords`
94
+
95
+ ```text
96
+ asyncio
97
+ batch computing
98
+ build automation
99
+ build tool
100
+ extension
101
+ high-performance computing
102
+ HPC
103
+ job scheduler
104
+ job submission
105
+ parallel
106
+ POSIX
107
+ Python
108
+ queued jobs
109
+ reproducibility
110
+ reproducible research
111
+ research software
112
+ SLURM
113
+ StepUp
114
+ StepUp Core
115
+ supercomputer
116
+ workflow automation
117
+ workflow management
118
+ ```
@@ -35,6 +35,17 @@ attaches to the job it already submitted, instead of submitting a second one:
35
35
  This is why the digest is written into the log rather than derived at read time:
36
36
  the log has to be interpretable by a process that never saw the original submission.
37
37
 
38
+ The invariant behind the contract is that at most one job runs per job directory,
39
+ because every job in it writes to the same `slurmjob.out`, `slurmjob.err` and `slurmjob.ret`.
40
+ Two places protect it:
41
+
42
+ - The `Submitting` marker is logged before `sbatch` runs and replaced by `Submitted <jobid>`
43
+ once the job ID is known.
44
+ A log that stops at the marker means the job ID may have been lost,
45
+ so the next run refuses to submit rather than risk a second job next to an untracked one.
46
+ - `onchange="resubmit"` waits for the cancelled job to leave the queue before resubmitting,
47
+ because `scancel` returns as soon as the request is accepted.
48
+
38
49
  ## sacct Caching
39
50
 
40
51
  All concurrent `sq-sbatch-and-wait` processes share one cached `sacct` result per cluster,
@@ -1,5 +1,5 @@
1
1
  # SPDX-FileCopyrightText: 2025 Toon Verstraelen <Toon.Verstraelen@UGent.be>
2
2
  # SPDX-License-Identifier: LGPL-3.0-or-later
3
- """StepUp Queue package."""
3
+ """Integrate SLURM jobs into a StepUp workflow."""
4
4
 
5
5
  __all__ = ()
@@ -1,25 +1,24 @@
1
1
  # SPDX-FileCopyrightText: 2025 Toon Verstraelen <Toon.Verstraelen@UGent.be>
2
2
  # SPDX-License-Identifier: LGPL-3.0-or-later
3
- """Tool to cancel jobs."""
3
+ """Cancel jobs that have been submitted to SLURM."""
4
4
 
5
5
  import argparse
6
6
  import subprocess
7
7
  import sys
8
- from collections.abc import Callable
8
+ from collections.abc import Sequence
9
9
 
10
10
  from path import Path
11
11
  from rich.console import Console
12
12
 
13
- from stepup.core.config import ConfigLoader
14
-
15
13
  from .log import read_jobid_cluster_status
16
14
  from .utils import DONE_STATES, search_jobs
17
15
 
18
- __all__ = ()
16
+ __all__ = ("cancel_jobs",)
19
17
 
20
18
 
21
- def canceljobs_tool(args: argparse.Namespace):
19
+ def cancel_jobs(argv: Sequence[str] | None = None):
22
20
  """Iterate over all slurmjob.log files, read the SLURM job IDs, and cancel them."""
21
+ args = parse_args(argv)
23
22
  console = Console(highlight=False)
24
23
  if not args.commit:
25
24
  console.print("[yellow]# Note: No jobs are actually cancelled.[/]")
@@ -41,18 +40,16 @@ def canceljobs_tool(args: argparse.Namespace):
41
40
  # Cancel at most 100 at a time to avoid exceeding the command line length limit,
42
41
  # and to play nice with SLURM.
43
42
  while len(cluster_jobs) > 0:
44
- cancel_jobs = cluster_jobs[:100]
43
+ batch = cluster_jobs[:100]
45
44
  cluster_jobs[:] = cluster_jobs[100:]
46
45
 
47
46
  command_args = ["scancel"]
48
47
  if cluster is not None:
49
48
  command_args.extend(["-M", cluster])
50
- command_args.extend(str(job_id) for job_id, _, _ in cancel_jobs)
49
+ command_args.extend(str(job_id) for job_id, _, _ in batch)
51
50
 
52
51
  # Using subprocess.run for better control and error handling
53
- print_cancel_command(
54
- console, [job_id for job_id, _, _ in cancel_jobs], cluster, None
55
- )
52
+ print_cancel_command(console, [job_id for job_id, _, _ in batch], cluster, None)
56
53
  result = subprocess.run(command_args, check=False)
57
54
  all_good &= result.returncode == 0
58
55
  else:
@@ -63,10 +60,11 @@ def canceljobs_tool(args: argparse.Namespace):
63
60
  sys.exit(1)
64
61
 
65
62
 
66
- def canceljobs_subcommand(subparsers, loader: ConfigLoader) -> Callable:
67
- parser = subparsers.add_parser(
68
- "canceljobs",
69
- help="Cancel running jobs in the current StepUp workflow.",
63
+ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
64
+ """Parse command-line arguments."""
65
+ parser = argparse.ArgumentParser(
66
+ prog="sq-cancel-jobs",
67
+ description="Cancel running jobs in the current StepUp workflow.",
70
68
  )
71
69
  parser.add_argument(
72
70
  "paths",
@@ -90,13 +88,12 @@ def canceljobs_subcommand(subparsers, loader: ConfigLoader) -> Callable:
90
88
  default=False,
91
89
  help="Select all jobs, including the ones that seem to be done already.",
92
90
  )
93
- loader.patch_parser(parser)
94
- return canceljobs_tool
91
+ return parser.parse_args(argv)
95
92
 
96
93
 
97
94
  def print_cancel_command(
98
95
  console: Console, job_ids: list[int], cluster: str | None, comment: str | None
99
- ) -> str:
96
+ ):
100
97
  """Print the job cancellation command."""
101
98
  parts = ["[green]scancel[/]"]
102
99
  if cluster is not None:
@@ -105,3 +102,7 @@ def print_cancel_command(
105
102
  if comment is not None:
106
103
  parts.append(f" [bright_black]# {comment}[/]")
107
104
  console.print(" ".join(parts))
105
+
106
+
107
+ if __name__ == "__main__":
108
+ sys.exit(cancel_jobs())
@@ -11,6 +11,8 @@ from .utils import parse_sbatch
11
11
  __all__ = (
12
12
  "FIRST_LINE",
13
13
  "InpDigestError",
14
+ "InterruptedSubmissionError",
15
+ "NoSubmissionError",
14
16
  "init_log",
15
17
  "log_status",
16
18
  "read_jobid_cluster_status",
@@ -25,6 +27,19 @@ class InpDigestError(ValueError):
25
27
  """The input digest in the log file does not match the one in the environment."""
26
28
 
27
29
 
30
+ class NoSubmissionError(ValueError):
31
+ """The log file holds no status lines, so no job was submitted yet."""
32
+
33
+
34
+ class InterruptedSubmissionError(ValueError):
35
+ """A submission was interrupted before the job ID could be written to the log.
36
+
37
+ The scheduler may or may not have accepted the job,
38
+ so a job may be running that StepUp Queue cannot identify.
39
+ Check the queue (e.g. with squeue) and remove the log file to submit again.
40
+ """
41
+
42
+
28
43
  def init_log(path_log: str, inp_digest: str):
29
44
  """Initialize a new log file."""
30
45
  with open(path_log, "w") as fh:
@@ -41,17 +56,34 @@ def log_status(path_log: Path, status: str):
41
56
 
42
57
 
43
58
  def read_jobid_cluster_status(path_log: str) -> tuple[int, str | None, str | None]:
44
- """Read the job ID, cluster, and job status from the job log file."""
59
+ """Read the job ID, cluster, and job status from the job log file.
60
+
61
+ Raises
62
+ ------
63
+ NoSubmissionError
64
+ When the log holds no status lines at all.
65
+ InterruptedSubmissionError
66
+ When the log stops at the `Submitting` marker.
67
+ ValueError
68
+ When the submission cannot be parsed.
69
+ """
45
70
  lines = read_log(path_log, None)
46
- if len(lines) < 1:
47
- raise ValueError(f"Incomplete file: {path_log}.")
71
+ if len(lines) == 0:
72
+ raise NoSubmissionError(f"No job was submitted according to {path_log}.")
73
+ # The submission is logged on the first status line,
74
+ # or on the second one when the first is the `Submitting` marker.
75
+ i_submitted = 0
48
76
  words = lines[0].split()
77
+ if len(words) == 2 and words[1] == "Submitting":
78
+ if len(lines) == 1:
79
+ raise InterruptedSubmissionError(f"No job ID was recorded in {path_log}.")
80
+ i_submitted = 1
81
+ words = lines[i_submitted].split()
49
82
  if len(words) != 3:
50
- raise ValueError(f"Could not read job ID from first status line: {lines[0]}")
51
- _, status, job_id_cluster = words
52
- if status != "Submitted":
53
- raise ValueError(f"No 'Submitted' on first status line: {lines[0]}")
54
- job_id, cluster = parse_sbatch(job_id_cluster)
83
+ raise ValueError(f"Could not read job ID from status line: {lines[i_submitted]}")
84
+ if words[1] != "Submitted":
85
+ raise ValueError(f"No 'Submitted' on status line: {lines[i_submitted]}")
86
+ job_id, cluster = parse_sbatch(words[2])
55
87
  status = read_status(lines[-1:])[1]
56
88
  return job_id, cluster, status
57
89