Skip to content

Commit 71dc2f1

Browse files
committed
docs: Correct the extends_symtab ordering comment
The comment justified running the symbol-table hook before the transform by saying StepTemplate's syntax-sugar transform folds step-level `let` bindings into the script. That fold was deleted in the previous commit, so the stated reason no longer exists -- but the ordering is still load-bearing, and this comment was its only record. Restate the two reasons that survive: * A transform may rebuild the model rather than adjust it -- `resolve_syntax_sugar` returns a `model_construct`ed StepTemplate -- so the fields the hook reads (`name`, `let`) are only guaranteed to be the authored ones on this side of it. The transform carries `let` through deliberately; running the hook first keeps that the transform's choice rather than a requirement on every future one. * `create_job_with_symbol_tables` invokes the same hook on the same untransformed StepTemplate to build the step symbol table it publishes for the runtime. That table is only the scope the step's own fields were instantiated against if both callers hand the hook the same model. Comment only; no behaviour change. Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
1 parent a7bb319 commit 71dc2f1

1 file changed

Lines changed: 15 additions & 4 deletions

File tree

‎src/openjd/model/_internal/_create_job.py‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -172,10 +172,21 @@ def instantiate_model( # noqa: C901
172172

173173
# Extend the symbol table for this model's subtree if defined (e.g. a
174174
# step's Step.Name and step-level EXPR `let` bindings). This runs before
175-
# the transform: StepTemplate's syntax-sugar transform folds step-level
176-
# `let` bindings into the script (their runtime channel), so the original
177-
# model is the one that still carries them for create_job-time fields
178-
# (parameter space, host requirements).
175+
# the transform, so the hook always sees the model as authored, and that
176+
# ordering is load-bearing for two reasons.
177+
#
178+
# A transform may rebuild the model rather than adjust it -- StepTemplate's
179+
# syntax-sugar transform returns a `model_construct`ed copy -- so the fields
180+
# the hook reads (a step's `name` and its `let`) are only guaranteed to be
181+
# the authored ones on this side of it. The current transform carries `let`
182+
# through deliberately; running the hook first is what keeps that the
183+
# transform's choice rather than a requirement on every future one.
184+
#
185+
# And create_job_with_symbol_tables invokes the same hook on the same
186+
# untransformed StepTemplate to build the step symbol table it publishes for
187+
# the runtime to seed a session with. That table is only the scope the
188+
# step's own fields (script, parameter space, host requirements) were
189+
# instantiated against if both callers hand the hook the same model.
179190
if model._job_creation_metadata.extends_symtab is not None:
180191
symtab = model._job_creation_metadata.extends_symtab(model, symtab)
181192

0 commit comments

Comments
 (0)