jpipe-runner 3.4.0__tar.gz → 3.5.0__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 (45) hide show
  1. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/PKG-INFO +31 -2
  2. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/README.md +30 -1
  3. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/pyproject.toml +1 -1
  4. jpipe_runner-3.5.0/src/jpipe_runner/exceptions.py +132 -0
  5. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/framework/decorators/jpipe_decorator.py +36 -5
  6. jpipe_runner-3.5.0/src/jpipe_runner/framework/decorators/link_decorator.py +51 -0
  7. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/framework/engine.py +159 -102
  8. jpipe_runner-3.5.0/src/jpipe_runner/framework/graphviz_exporter.py +106 -0
  9. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/framework/logger.py +19 -5
  10. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/__init__.py +21 -0
  11. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/base.py +41 -0
  12. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/duplicate_producer.py +47 -0
  13. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/evidence_dependency.py +186 -0
  14. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/missing_variable.py +54 -0
  15. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/order.py +77 -0
  16. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/produced_not_consumed.py +46 -0
  17. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/schema.py +92 -0
  18. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/self_dependency.py +47 -0
  19. jpipe_runner-3.5.0/src/jpipe_runner/framework/validators/unbound_element.py +56 -0
  20. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/runner.py +57 -45
  21. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/runtime.py +30 -9
  22. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/schema/justification.schema.json +1 -0
  23. jpipe_runner-3.5.0/src/jpipe_runner/utils/__init__.py +15 -0
  24. jpipe_runner-3.5.0/src/jpipe_runner/utils/append_else_default_action.py +73 -0
  25. jpipe_runner-3.5.0/src/jpipe_runner/utils/group_loggers/__init__.py +39 -0
  26. jpipe_runner-3.5.0/src/jpipe_runner/utils/group_loggers/base.py +35 -0
  27. jpipe_runner-3.5.0/src/jpipe_runner/utils/group_loggers/github_actions.py +38 -0
  28. jpipe_runner-3.5.0/src/jpipe_runner/utils/group_loggers/plain.py +30 -0
  29. jpipe_runner-3.4.0/src/jpipe_runner/utils.py → jpipe_runner-3.5.0/src/jpipe_runner/utils/parsing.py +5 -52
  30. jpipe_runner-3.5.0/src/jpipe_runner/utils/sanitize.py +17 -0
  31. jpipe_runner-3.5.0/src/jpipe_runner/utils/syspath.py +40 -0
  32. jpipe_runner-3.5.0/src/jpipe_runner/utils/terminal.py +25 -0
  33. jpipe_runner-3.4.0/src/jpipe_runner/exceptions.py +0 -30
  34. jpipe_runner-3.4.0/src/jpipe_runner/framework/decorators/link_decorator.py +0 -33
  35. jpipe_runner-3.4.0/src/jpipe_runner/framework/validators.py +0 -591
  36. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/LICENSE +0 -0
  37. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/__init__.py +0 -0
  38. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/__main__.py +0 -0
  39. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/enums.py +0 -0
  40. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/framework/__init__.py +0 -0
  41. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/framework/context.py +0 -0
  42. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/framework/decorators/__init__.py +0 -0
  43. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/framework/decorators/contribution_decorator.py +0 -0
  44. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/framework/decorators/skip_decorator.py +0 -0
  45. {jpipe_runner-3.4.0 → jpipe_runner-3.5.0}/src/jpipe_runner/schema/__init__.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jpipe-runner
3
- Version: 3.4.0
3
+ Version: 3.5.0
4
4
  Summary: A Justification Runner designed for jPipe.
5
5
  License: MIT
6
6
  License-File: LICENSE
@@ -92,9 +92,37 @@ poetry run pytest
92
92
  poetry build
93
93
  ```
94
94
 
95
+ ## 🏷️ Releasing
96
+
97
+ Releases are cut from `dev` and published automatically when a version tag is
98
+ pushed. See [`CHANGELOG.md`](CHANGELOG.md) for the release history.
99
+
100
+ 1. **Bump the version** in `pyproject.toml` (single source of truth — `setup.py`
101
+ and the docs derive from it). Follow [SemVer](https://semver.org): patch for
102
+ fixes, minor for backward-compatible features, major for breaking changes.
103
+ 2. **Update `CHANGELOG.md`** — move the relevant notes under a new
104
+ `## [x.y.z] - YYYY-MM-DD` heading.
105
+ 3. **Open a PR `dev → main`** and merge once CI is green.
106
+ 4. **Tag the merged commit** on `main` and push it:
107
+ ```bash
108
+ git checkout main && git pull
109
+ git tag vX.Y.Z # must equal the pyproject.toml version
110
+ git push origin vX.Y.Z
111
+ ```
112
+
113
+ Pushing the `vX.Y.Z` tag triggers the release pipeline
114
+ ([`.github/workflows/release.yml`](.github/workflows/release.yml)), which
115
+ validates the tag/version match, runs the tests, builds the docs, wheel, sdist
116
+ and signed `.deb`, then publishes to **GitHub Releases**, **PyPI**, the **Ubuntu
117
+ PPA**, and the **Homebrew** tap, and deploys the docs to GitHub Pages.
118
+
119
+ > The tag version **must** match `pyproject.toml` exactly, or the pipeline fails
120
+ > at the `validate-version` step.
121
+
95
122
  ## 📚 Learn More
96
123
 
97
124
  * [Usage Guide](docs/USAGE.md)
125
+ * [Releasing](#-releasing) · [Changelog](CHANGELOG.md)
98
126
  * [Packaging & CI/CD](docs/PACKAGING_RELEASE.md)
99
127
  * [Troubleshooting](docs/TROUBLESHOOTING.md)
100
128
  * [Developer Docs (Sphinx)](docs/BUILD_DOCS.md)
@@ -109,12 +137,13 @@ MIT License — see [LICENSE](LICENSE).
109
137
  * [Jason Lyu](https://github.com/xjasonlyu)
110
138
  * [Baptiste Lacroix](https://github.com/BaptisteLacroix)
111
139
  * [Sébastien Mosser](https://github.com/mosser)
140
+ * [Corentin Veillard](https://github.com/corentinVei)
112
141
 
113
142
  ## How to cite?
114
143
 
115
144
  ```bibtex
116
145
  @software{mcscert:jpipe-runner,
117
- author = {Mosser, Sébastien and Lyu, Jason and Lacroix, Baptiste},
146
+ author = {Mosser, Sébastien and Lyu, Jason and Lacroix, Baptiste, and Corentin Veillard},
118
147
  license = {MIT},
119
148
  title = {{jPipe Runner}},
120
149
  url = {https://github.com/ace-design/jpipe-runner}
@@ -65,9 +65,37 @@ poetry run pytest
65
65
  poetry build
66
66
  ```
67
67
 
68
+ ## 🏷️ Releasing
69
+
70
+ Releases are cut from `dev` and published automatically when a version tag is
71
+ pushed. See [`CHANGELOG.md`](CHANGELOG.md) for the release history.
72
+
73
+ 1. **Bump the version** in `pyproject.toml` (single source of truth — `setup.py`
74
+ and the docs derive from it). Follow [SemVer](https://semver.org): patch for
75
+ fixes, minor for backward-compatible features, major for breaking changes.
76
+ 2. **Update `CHANGELOG.md`** — move the relevant notes under a new
77
+ `## [x.y.z] - YYYY-MM-DD` heading.
78
+ 3. **Open a PR `dev → main`** and merge once CI is green.
79
+ 4. **Tag the merged commit** on `main` and push it:
80
+ ```bash
81
+ git checkout main && git pull
82
+ git tag vX.Y.Z # must equal the pyproject.toml version
83
+ git push origin vX.Y.Z
84
+ ```
85
+
86
+ Pushing the `vX.Y.Z` tag triggers the release pipeline
87
+ ([`.github/workflows/release.yml`](.github/workflows/release.yml)), which
88
+ validates the tag/version match, runs the tests, builds the docs, wheel, sdist
89
+ and signed `.deb`, then publishes to **GitHub Releases**, **PyPI**, the **Ubuntu
90
+ PPA**, and the **Homebrew** tap, and deploys the docs to GitHub Pages.
91
+
92
+ > The tag version **must** match `pyproject.toml` exactly, or the pipeline fails
93
+ > at the `validate-version` step.
94
+
68
95
  ## 📚 Learn More
69
96
 
70
97
  * [Usage Guide](docs/USAGE.md)
98
+ * [Releasing](#-releasing) · [Changelog](CHANGELOG.md)
71
99
  * [Packaging & CI/CD](docs/PACKAGING_RELEASE.md)
72
100
  * [Troubleshooting](docs/TROUBLESHOOTING.md)
73
101
  * [Developer Docs (Sphinx)](docs/BUILD_DOCS.md)
@@ -82,12 +110,13 @@ MIT License — see [LICENSE](LICENSE).
82
110
  * [Jason Lyu](https://github.com/xjasonlyu)
83
111
  * [Baptiste Lacroix](https://github.com/BaptisteLacroix)
84
112
  * [Sébastien Mosser](https://github.com/mosser)
113
+ * [Corentin Veillard](https://github.com/corentinVei)
85
114
 
86
115
  ## How to cite?
87
116
 
88
117
  ```bibtex
89
118
  @software{mcscert:jpipe-runner,
90
- author = {Mosser, Sébastien and Lyu, Jason and Lacroix, Baptiste},
119
+ author = {Mosser, Sébastien and Lyu, Jason and Lacroix, Baptiste, and Corentin Veillard},
91
120
  license = {MIT},
92
121
  title = {{jPipe Runner}},
93
122
  url = {https://github.com/ace-design/jpipe-runner}
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "jpipe-runner"
3
- version = "3.4.0"
3
+ version = "3.5.0"
4
4
  description = "A Justification Runner designed for jPipe."
5
5
  authors = [
6
6
  "Jason Lyu <xjasonlyu@gmail.com>",
@@ -0,0 +1,132 @@
1
+ """
2
+ jpipe_runner.exceptions
3
+ ~~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+ This module contains the set of jPipe Runner's exceptions.
6
+ """
7
+
8
+ import sys
9
+
10
+ from jpipe_runner.framework.logger import log_buffer
11
+
12
+ # https://patorjk.com/software/taag/#p=display&f=Ivrit&t=STDERR%20OUTPUT%20BEGIN
13
+ STDERR_OUTPUT_BEGIN = r"""
14
+
15
+ _____ ____ ____ ___ ____ _ ___ ____
16
+ | ____| _ \| _ \ / _ \| _ \ | | / _ \ / ___|
17
+ | _| | |_) | |_) | | | | |_) | | | | | | | | _
18
+ | |___| _ <| _ <| |_| | _ < | |__| |_| | |_| |
19
+ |_____|_| \_\_| \_\\___/|_| \_\ |_____\___/ \____|
20
+
21
+
22
+ """
23
+
24
+
25
+ class RunnerException(Exception):
26
+ """There was an ambiguous exception that occurred while running the runner."""
27
+
28
+
29
+ class SyntaxException(SyntaxError, RunnerException):
30
+ """A syntax error occurred."""
31
+
32
+
33
+ class InvalidJustificationException(RunnerException):
34
+ """An invalid justification error occurred."""
35
+
36
+
37
+ class JustificationTraverseException(RunnerException):
38
+ """A justification layered traverse error occurred."""
39
+
40
+
41
+ class RuntimeException(RuntimeError, RunnerException):
42
+ """A runtime error of jpipe runner occurred."""
43
+
44
+
45
+ class FunctionException(RunnerException):
46
+ """A justification function error occurred."""
47
+
48
+
49
+ class WorkflowError(Exception):
50
+ """
51
+ Base exception for workflow errors that should terminate execution.
52
+ Also prints the error message to stderr when `handle` is called if a message is provided.
53
+ """
54
+
55
+ def __init__(self, message: str | None = None, exit_code: int = 1):
56
+ super().__init__(message)
57
+ self.message = message
58
+ self.exit_code = exit_code
59
+
60
+ def handle(self):
61
+ """Print the error message to stderr only if it is not None."""
62
+ if self.message is not None:
63
+ print(self.message, file=sys.stderr)
64
+
65
+
66
+ class WorkflowErrorWithLogDump(WorkflowError):
67
+ """A workflow error that also prints the log buffer to stderr on `handle`."""
68
+
69
+ def handle(self):
70
+ """Print the error message (if any), then dump the log buffer."""
71
+ super().handle()
72
+
73
+ print(STDERR_OUTPUT_BEGIN, file=sys.stderr)
74
+ log_buffer.dump_to_stderr()
75
+
76
+
77
+ class NoJustificationFileError(WorkflowError):
78
+ """Raised when no justification file argument is provided."""
79
+
80
+ def __init__(self):
81
+ super().__init__("No justification json file provided. Please specify a .json file.")
82
+
83
+
84
+ class InvalidJustificationFileError(WorkflowError):
85
+ """Raised when the justification file is not a .json file."""
86
+
87
+ def __init__(self):
88
+ super().__init__("The provided justification file is not a .json file.")
89
+
90
+
91
+ class LibraryNotFoundError(WorkflowError):
92
+ """Raised when one or more library paths do not match any files."""
93
+
94
+ def __init__(self, not_matched_files: list[str]):
95
+ msg = (
96
+ f"No library found for path(s): {', '.join(not_matched_files)}\n"
97
+ "Please check the provided library paths."
98
+ )
99
+ super().__init__(msg)
100
+
101
+
102
+ class RuntimeInitializationError(WorkflowError):
103
+ """Raised when the Python runtime throws an exception during initialization."""
104
+
105
+ def __init__(self, message: str):
106
+ super().__init__(message)
107
+
108
+
109
+ class DryRunError(WorkflowErrorWithLogDump):
110
+ """
111
+ Raised when a dry-run completes but the log buffer contains errors.
112
+ Only prints the log buffer to stderr, without any additional message.
113
+ """
114
+
115
+ def __init__(self):
116
+ super().__init__(None)
117
+
118
+
119
+ class StreamOutputNotSupportedError(WorkflowError):
120
+ """Raised when the output path is set to stdout or stderr."""
121
+
122
+ def __init__(self):
123
+ super().__init__("Streamed diagram output is not supported yet.")
124
+
125
+
126
+ class UnsupportedOutputFormatError(WorkflowErrorWithLogDump):
127
+ """Raised when an unsupported image export format is provided."""
128
+
129
+ def __init__(self, format: str, supported_formats: list[str]):
130
+ super().__init__(
131
+ f"Unsupported output format: {format}. Supported formats are: {', '.join(supported_formats)}"
132
+ )
@@ -21,8 +21,11 @@ def jpipe(consume: Optional[List[str]] = None, produce: Optional[List[str]] = No
21
21
  produce = produce or []
22
22
 
23
23
  def decorator(func: Callable) -> Callable:
24
+ _check_produce_param(func, produce)
24
25
  consume_checker = _init_checker(ConsumedVariableChecker, func, consume)
25
26
  produce_checker = _init_checker(ProducedVariableChecker, func, produce)
27
+ params = list(inspect.signature(func).parameters)
28
+ _has_produce_slot = bool(params) and params[-1] == "produce"
26
29
 
27
30
  @wraps(func)
28
31
  def wrapper(*args: Any, **kwargs: Any) -> Any:
@@ -30,6 +33,8 @@ def jpipe(consume: Optional[List[str]] = None, produce: Optional[List[str]] = No
30
33
  kwargs = consume_checker.inject_arguments(kwargs)
31
34
  if produce_checker:
32
35
  kwargs["produce"] = produce_checker.produce
36
+ elif _has_produce_slot:
37
+ kwargs["produce"] = _noop_produce
33
38
 
34
39
  result = func(*args, **kwargs)
35
40
 
@@ -43,6 +48,26 @@ def jpipe(consume: Optional[List[str]] = None, produce: Optional[List[str]] = No
43
48
  return decorator
44
49
 
45
50
 
51
+ def _check_produce_param(func: Callable, produce: List[str]) -> None:
52
+ if not produce:
53
+ return
54
+ params = list(inspect.signature(func).parameters)
55
+ if not params or params[-1] != "produce":
56
+ raise ValueError(
57
+ f"[jpipe] Function '{func.__name__}' declares produce={produce!r} "
58
+ f"but its last parameter is not 'produce'.\n"
59
+ f" • Actual signature: {func.__name__}({', '.join(params)})\n"
60
+ f" • Fix: add 'produce' as the final parameter, "
61
+ f"typed as Callable[[str, Any], None]."
62
+ )
63
+
64
+
65
+ def _noop_produce(name: str, value: Any) -> None:
66
+ # Intentional no-op: allows functions to keep a produce param for consistency
67
+ # when produce=[] — calls are accepted and silently discarded.
68
+ pass
69
+
70
+
46
71
  def _init_checker(
47
72
  CheckerClass: type, func: Callable, params: List[str]
48
73
  ) -> "ConsumedVariableChecker | ProducedVariableChecker | None":
@@ -93,6 +118,15 @@ class ConsumedVariableChecker:
93
118
  ctx._set(self.func_name, param, None, RuntimeContext.CONSUME)
94
119
  GLOBAL_LOGGER.debug(f"[{self.func_name}] Variable '{param}' registered as CONSUME")
95
120
 
121
+ unused = set(self.declared_params) - self.used_params
122
+ if unused:
123
+ raise ValueError(
124
+ f"[jpipe] Function '{self.func_name}' declares consumed variable(s) "
125
+ f"{sorted(unused)!r} that are never referenced in the function body.\n"
126
+ f" • Fix: either reference each variable in the function body, "
127
+ f"or remove it from consume=[]."
128
+ )
129
+
96
130
  def inject_arguments(self, kwargs: dict) -> dict:
97
131
  """
98
132
  Injects variable values from the context into the function’s keyword arguments.
@@ -102,10 +136,6 @@ class ConsumedVariableChecker:
102
136
  :raises ValueError: If a declared variable is missing from the context.
103
137
  """
104
138
  for param in self.declared_params:
105
- if param not in self.used_params:
106
- GLOBAL_LOGGER.warning(
107
- f"Consumed variable '{param}' is declared but not used in function '{self.func_name}'."
108
- )
109
139
  value = ctx.get(param)
110
140
  GLOBAL_LOGGER.debug(
111
141
  f"[{self.func_name}] Injecting consumed variable '{param}' = {value}"
@@ -136,7 +166,8 @@ class ConsumedVariableChecker:
136
166
  self.used_vars: set[str] = set()
137
167
 
138
168
  def visit_Name(self, node: ast.Name) -> None:
139
- self.used_vars.add(node.id)
169
+ if isinstance(node.ctx, ast.Load):
170
+ self.used_vars.add(node.id)
140
171
 
141
172
  visitor = VarVisitor()
142
173
  visitor.visit(tree)
@@ -0,0 +1,51 @@
1
+ from typing import Callable, TypeVar
2
+
3
+ F = TypeVar("F", bound=Callable)
4
+
5
+
6
+ def jpipe_link(element_id: str) -> Callable[[F], F]:
7
+ """
8
+ Decorator to explicitly bind a Python function to a JSON pipeline element by its id.
9
+
10
+ This removes the fragile label-to-function-name mapping: instead of requiring
11
+ the function name to match the sanitized form of the JSON label, the decorator
12
+ records the element id directly on the function.
13
+
14
+ The decorator may be stacked multiple times to bind one function to several
15
+ names — all expected to be aliases of the same unified node. Each application
16
+ appends to the ``__jpipe_link_ids__`` list rather than overwriting, so no
17
+ binding is silently lost.
18
+
19
+ Compatible with @jpipe, @skip, and @contribution in any stacking order, because
20
+ all three use @wraps which propagates __dict__ attributes to their wrappers.
21
+
22
+ The id need not be the full node id or alias: a trailing colon-separated
23
+ *suffix* also binds, so identical logic can be reused across contexts without
24
+ re-annotating every fully-qualified id. ``@jpipe_link("e_metric")`` and
25
+ ``@jpipe_link("r17:e_metric")`` both bind ``rigor:r17:e_metric``; ``"r17"`` alone
26
+ does not (it is not a trailing suffix). A suffix that matches more than one node
27
+ is ambiguous and reported as a pipeline validation error.
28
+
29
+ :param element_id: The id, alias, or trailing segment-suffix of the JSON element
30
+ this function implements (e.g. "E1", "rigor:r17:e_metric", or "e_metric").
31
+ :type element_id: str
32
+
33
+ Example::
34
+
35
+ @jpipe_link("rigor:r17:e_metric")
36
+ @jpipe_link("rigor:r18:e")
37
+ @jpipe(consume=["file_path"], produce=["file_exists"])
38
+ def check_file(file_path, produce):
39
+ produce("file_exists", os.path.isfile(file_path))
40
+ return True
41
+ """
42
+
43
+ def decorator(func: F) -> F:
44
+ ids = getattr(func, "__jpipe_link_ids__", None)
45
+ if ids is None:
46
+ ids = []
47
+ func.__jpipe_link_ids__ = ids
48
+ ids.append(element_id)
49
+ return func
50
+
51
+ return decorator