Skip to content

Commit ffd4be3

Browse files
committed
docs: Document the create_job step-let contract as breaking
Dropping the step-level `let` merge means the Job returned by plain create_job() is no longer self-contained for an EXPR template whose step declares a `let` its script references: at 6a23815 script.let was ['a = 1'] and the task succeeded; at 260b147 script.let is None and the task fails with `Undefined variable: 'a'`. The removal is correct -- both channels evaluating caused the clobber this branch fixes -- so document the contract instead of adding a shim. Rewrite create_job's docstring to say plainly that the Job does not carry step-level `let` values and that a caller running such a job must use create_job_with_symbol_tables and forward the tables, add a CHANGELOG breaking-change entry, and add the same pointer to the README's "Creating a Job from a Job Template" example. The README's other two create_job() examples only inspect the Job at creation time (StepDependencyGraph, StepParameterSpaceIterator), so plain create_job stays correct there and they are left alone. BREAKING CHANGE: create_job() no longer returns a Job carrying evaluated step-level `let` values. A caller that runs a job whose steps declare a template-scope `let` referenced from the step's script must switch to create_job_with_symbol_tables and forward the step's step_symbol_tables entry to the session. Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
1 parent 71dc2f1 commit ffd4be3

3 files changed

Lines changed: 39 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,17 @@
1+
## Unreleased
2+
3+
### BREAKING CHANGES
4+
* Step-level `let` bindings are evaluated once in template scope and are no longer merged into the step's script, so the `Job`
5+
returned by `create_job` no longer carries their values. A caller that runs a job whose steps declare a template-scope `let`
6+
referenced from the step's script must switch to `create_job_with_symbol_tables` and forward the step's `step_symbol_tables`
7+
entry to the session; otherwise the action fails at run time with `Undefined variable`. Callers that only inspect the `Job`
8+
at creation time — `StepDependencyGraph`, `StepParameterSpaceIterator`, `hostRequirements` — are unaffected.
9+
10+
### Bug Fixes
11+
* Evaluate step-level let bindings in template scope
12+
* Stop merging step-level let into the script
13+
14+
115
## 0.11.7 (2026-09-01)
216

317

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,15 @@ except (DecodeValidationError, RuntimeError) as e:
211211
print(str(e))
212212
```
213213

214+
If any of the job's steps declares a template-scope `let` that the step's script
215+
references, then this `Job` is not sufficient to run the step: step-level `let`
216+
bindings are evaluated once during instantiation and kept in the step's symbol
217+
table rather than lowered onto the script, so a session created from the `Job`
218+
alone has no binding for the name and the action fails with `Undefined variable`.
219+
Use `create_job_with_symbol_tables` instead and forward the step's entry from the
220+
returned `step_symbol_tables` to the session that runs it. The two examples below
221+
only inspect the `Job` at creation time, so plain `create_job` is correct there.
222+
214223
### Working with Step dependencies
215224

216225
```python

‎src/openjd/model/_create_job.py‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -529,15 +529,27 @@ def create_job(
529529
) -> Job:
530530
"""Create a job from a Job Template and a set of Job Parameter values.
531531
532-
See :func:`create_job_with_symbol_tables` when you also need the resolved
533-
symbol tables — for instance to transport them to a host that will run the
534-
job's sessions.
532+
The returned ``Job`` does not carry the evaluated step-level ``let`` values.
533+
Those bindings are template-scope: they are evaluated once here, in template
534+
scope, and kept in the step-scope symbol table rather than lowered onto the
535+
step's script. So for a template that declares a step-level ``let`` and
536+
references it from the step's script, this ``Job`` alone is not enough to run
537+
the step — the session has no binding for the name and the action fails with
538+
``Undefined variable``.
539+
540+
A caller that intends to *run* such a job must use
541+
:func:`create_job_with_symbol_tables` instead, and forward the returned
542+
``step_symbol_tables`` entry for the step to the session that runs it. Callers
543+
that only inspect the ``Job`` at creation time — a ``StepDependencyGraph``, a
544+
``StepParameterSpaceIterator``, ``hostRequirements`` — are unaffected, because
545+
those fields are resolved during instantiation and already hold their values.
535546
536547
Raises:
537548
DecodeValidationError
538549
539550
Returns:
540-
Job: The job generated.
551+
Job: The job generated. Self-contained only if no step declares a
552+
template-scope ``let`` that its script references.
541553
"""
542554
job, _symtab = _create_job_and_symbol_table(
543555
job_template=job_template,

0 commit comments

Comments
 (0)