Skip to content

Commit 7d8e4df

Browse files
author
Markus
committed
docs(workflows): warn that path keys outside [\w-] no longer resolve
The docs said the former engine looked up a key such as `{{ inputs.weird:key }}` as a path and rendered the miss as an empty string or `None`. When the key existed, the lookup resolved to its value, so a workflow that uses such a key worked before and now fails with a ValueError at run time. Correct the claim in workflows/ARCHITECTURE.md, the engine docstring and the test docstring, and add a compatibility note to the workflow reference: rename the key and its references, since quoted-key lookup is not supported and validation may not catch these expressions before a run. Assisted-by: Pi Coding Agent (model: claude-opus-5.5, autonomous)
1 parent 23faa2d commit 7d8e4df

4 files changed

Lines changed: 7 additions & 4 deletions

File tree

‎docs/reference/workflows.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1298,6 +1298,8 @@ Operators bind from loosest to tightest as `or`, `and`, `not`, then the comparis
12981298

12991299
The body of every `{{ }}` block must be a valid expression. Text that is not one, such as prose (`{{ some text }}`), a key with characters other than letters, digits, `_` and `-` (`{{ inputs.weird:key }}`), or arithmetic (`{{ count + 1 }}`), raises a `ValueError` naming the offending token. Numbers may be written as `5`, `-5`, `+5`, `1_000`, `0.5`, `.5`, `5.`, or `1.5e3`.
13001300

1301+
> **Compatibility:** Earlier releases could resolve an expression such as `{{ inputs.weird:key }}` when the key existed; this expression now fails at runtime. Rename keys you control (for example, `weird:key` to `weird_key`) and update their references. Quoted-key lookup is not supported. Workflow validation may not detect these expressions before execution.
1302+
13011303
Example:
13021304

13031305
```yaml

‎src/specify_cli/workflows/expressions/engine.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@
88
(``a == b > 0`` is ``(a == b) > 0``). The former engine's operator scan order
99
gave them accidental priorities; parenthesize to combine comparisons.
1010
* Text that is not an expression -- prose inside ``{{ }}``, path keys with
11-
characters outside ``[\\w-]`` -- is a syntax error instead of a ``None`` lookup.
11+
characters outside ``[\\w-]`` -- is a syntax error instead of a path lookup,
12+
which could resolve an existing key.
1213
1314
The rest of this docstring describes how the engine is built:
1415

‎tests/test_workflows.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1795,8 +1795,8 @@ def test_operator_after_a_filter_chain_is_a_filter_precedence_error(self):
17951795

17961796
def test_text_that_is_not_an_expression_is_refused(self):
17971797
"""Prose inside ``{{ }}`` and path keys outside ``[\\w-]`` are syntax
1798-
errors. The former engine looked them up as paths and rendered the
1799-
miss as an empty string or ``None``."""
1798+
errors. The former engine looked them up as paths and could resolve an
1799+
existing key."""
18001800
import pytest
18011801
from specify_cli.workflows.expressions import evaluate_expression
18021802
from specify_cli.workflows.base import StepContext

‎workflows/ARCHITECTURE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ Workflow definitions use Jinja2-like `{{ expression }}` syntax for dynamic value
208208

209209
**Operator precedence.** From loosest to tightest: `or`, `and`, `not`, then the comparisons (`==`, `!=`, `>`, `<`, `>=`, `<=`, `in`, `not in`). All comparisons share **one** level and group left to right, so no comparison has priority over another: `{{ a == b > 0 }}` is `{{ (a == b) > 0 }}`, and `{{ 1 < 2 < 3 }}` is `{{ (1 < 2) < 3 }}`. The former hand-written engine gave comparisons accidental priorities through its operator scan order; parenthesize, or join comparisons with `and`/`or`, instead of relying on either reading. A `not` on the right of a comparison negates only its operand: `{{ a == not b }}`.
210210

211-
**Only expressions parse.** The body of every `{{ }}` block is parsed by a grammar, so text that is not an expression is a `ValueError` naming the offending token and column: prose such as `{{ some text }}`, path keys with characters outside letters, digits, `_` and `-` (`{{ inputs.weird:key }}`), arithmetic, or two adjacent operands. The former engine looked such text up as a path and rendered the miss as an empty string or `None`. Validation of `if`/`while`/`do-while` conditions checks only the `{{ }}` delimiters and layout, not the expression inside: `{{ inputs.count + 1 }}` passes validation and fails with the `ValueError` when the step runs, as do all other fields.
211+
**Only expressions parse.** The body of every `{{ }}` block is parsed by a grammar, so text that is not an expression is a `ValueError` naming the offending token and column: prose such as `{{ some text }}`, path keys with characters outside letters, digits, `_` and `-` (`{{ inputs.weird:key }}`), arithmetic, or two adjacent operands. The former engine looked such text up as a path: an existing key such as `inputs.weird:key` could resolve successfully, while a miss rendered as an empty string or `None`. Validation of `if`/`while`/`do-while` conditions checks only the `{{ }}` delimiters and layout, not the expression inside: `{{ inputs.count + 1 }}` passes validation and fails with the `ValueError` when the step runs, as do all other fields.
212212

213213
**Filter argument strictness (new filters).** The five filters added in #4766 validate their supported inputs and raise `ValueError` naming the problem rather than leaking a Python `TypeError`/`AttributeError`: `upper`/`lower` accept only strings, `split` requires a string value and a non-empty string separator, `length` accepts only lists and strings, and `to_json` requires a JSON-serializable value whose mapping keys are strings, and additionally rejects non-finite floats (`NaN`, `Infinity`, `-Infinity`), which `json.dumps` would otherwise emit as bare tokens that are not valid JSON. Keys are checked before serialization because `json.dumps` would otherwise coerce `1` to `"1"` (colliding with an existing `"1"` key), while `sort_keys=True` raises an ordering `TypeError` on mixed key types — both surfacing as a generic "not JSON-serializable" that hides the authoring mistake. Coercion is deliberately rejected for these filters: a type mismatch almost always means the pipeline is wired to the wrong variable, and a coerced result (e.g. `"3"` for an int) would hide that. Arity is checked before the argument expression is evaluated, so a filter used with the wrong number of arguments — `| upper('x')`, `| split` with no separator, `| split(',', 1)`, `| join` bare — is reported as a known filter misused, distinct from an entirely unknown name.
214214

0 commit comments

Comments
 (0)