π« Toolkit to help you get started with SDD or any other process!
feat(workflows): add from_json expression filter (#2961)
Huy Doaffbf5ead55b
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.mdindex 9e0c6f2e7..5f6e90d92 100644--- a/docs/reference/workflows.md+++ b/docs/reference/workflows.md@@ -280,7 +280,7 @@ Steps can reference inputs and previous step outputs using `{{ expression }}` sy| `steps.specify.output.file` | Output from a previous step || `item` | Current item in a fan-out iteration |-Available filters: `default`, `join`, `contains`, `map`.+Available filters: `default`, `join`, `contains`, `map`, `from_json`.Example:diff --git a/src/specify_cli/workflows/expressions.py b/src/specify_cli/workflows/expressions.pyindex 3cc74c764..6259b59de 100644--- a/src/specify_cli/workflows/expressions.py+++ b/src/specify_cli/workflows/expressions.py@@ -1,11 +1,13 @@"""Sandboxed expression evaluator for workflow templates.Provides a safe Jinja2 subset for evaluating expressions in workflow YAML.-No file I/O, no imports, no arbitrary code execution.+Templates cannot perform file I/O, import modules, or run arbitrary code β+the evaluator only walks the namespace and applies a fixed set of filters."""from __future__ import annotations+import jsonimport refrom typing import Any@@ -57,6 +59,23 @@ def _filter_contains(value: Any, substring: str) -> bool:return False+def _filter_from_json(value: Any) -> Any:+ """Parse a JSON string into a typed value (list/dict/scalar).++ Raises ``ValueError`` on non-string input or invalid JSON β a parse+ failure here means the pipeline wiring is wrong, and silently+ passing the unparsed value through would hide it.+ """+ if not isinstance(value, str):+ raise ValueError(+ f"from_json: expected a JSON string, got {type(value).__name__}"+ )+ try:+ return json.loads(value)+ except json.JSONDecodeError as exc:+ raise ValueError(f"from_json: invalid JSON: {exc}") from exc++# -- Expression resolution ------------------------------------------------_EXPR_PATTERN = re.compile(r"\{\{(.+?)\}\}")@@ -122,7 +141,7 @@ def _evaluate_simple_expression(expr: str, namespace: dict[str, Any]) -> Any:- Comparisons: ``==``, ``!=``, ``>``, ``<``, ``>=``, ``<=``- Boolean operators: ``and``, ``or``, ``not``- ``in``, ``not in``- - Pipe filters: ``| default('...')``, ``| join(', ')``, ``| contains('...')``, ``| map('...')``+ - Pipe filters: ``| default('...')``, ``| join(', ')``, ``| contains('...')``, ``| from_json``, ``| map('...')``- String and numeric literals"""expr = expr.strip()@@ -140,6 +159,22 @@ def _evaluate_simple_expression(expr: str, namespace: dict[str, Any]) -> Any:value = _evaluate_simple_expression(parts[0].strip(), namespace)filter_expr = parts[1].strip()+ # `from_json` is strict: it takes no arguments and tolerates no+ # trailing tokens. Match on the leading filter name and require the+ # whole filter to be exactly `from_json`, so every mis-wired form+ # (`from_json()`, `from_json('x')`, `from_json)`, `from_json extra`)+ # fails loudly instead of silently falling through to the+ # unknown-filter path and returning the unparsed value. (filter_expr+ # is already stripped above.)+ leading = re.match(r"\w+", filter_expr)+ if leading and leading.group(0) == "from_json":+ if filter_expr != "from_json":+ raise ValueError(+ "from_json: expected '| from_json' with no arguments or "+ f"trailing tokens, got '| {filter_expr}'"+ )+ return _filter_from_json(value)+# Parse filter name and argumentfilter_match = re.match(r"(\w+)\((.+)\)", filter_expr)if filter_match:diff --git a/tests/test_workflows.py b/tests/test_workflows.pyindex 6bd49f197..a87c09cf0 100644--- a/tests/test_workflows.py+++ b/tests/test_workflows.py@@ -289,6 +289,59 @@ class TestExpressions:ctx = StepContext(inputs={"text": "hello world"})assert evaluate_expression("{{ inputs.text | contains('world') }}", ctx) is True+ def test_filter_from_json_parses_object(self):+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(+ steps={"emit": {"output": {"stdout": '{"items": [1, 2, 3]}'}}}+ )+ result = evaluate_expression("{{ steps.emit.output.stdout | from_json }}", ctx)+ assert result == {"items": [1, 2, 3]}++ def test_filter_from_json_invalid_json_raises(self):+ import pytest+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(steps={"emit": {"output": {"stdout": "not json"}}})+ with pytest.raises(ValueError, match="from_json: invalid JSON"):+ evaluate_expression("{{ steps.emit.output.stdout | from_json }}", ctx)++ def test_filter_from_json_non_string_raises(self):+ import pytest+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(steps={"emit": {"output": {"exit_code": 0}}})+ with pytest.raises(ValueError, match="expected a JSON string"):+ evaluate_expression("{{ steps.emit.output.exit_code | from_json }}", ctx)++ def test_filter_from_json_rejects_malformed_forms(self):+ # `from_json` is strict: no arguments and no trailing tokens. Every+ # mis-wired form β parenthesized, accidental arg, or trailing+ # garbage β must raise rather than silently fall through to the+ # unknown-filter path and return the unparsed value.+ import pytest+ from specify_cli.workflows.expressions import evaluate_expression+ from specify_cli.workflows.base import StepContext++ ctx = StepContext(steps={"emit": {"output": {"stdout": '{"a": 1}'}}})+ bad_forms = (+ "from_json()",+ "from_json('x')",+ "from_json ()",+ "from_json ('x')",+ "from_json)",+ "from_json extra",+ "from_json 'x'",+ )+ for bad in bad_forms:+ with pytest.raises(ValueError, match="from_json: expected"):+ evaluate_expression(+ "{{ steps.emit.output.stdout | " + bad + " }}", ctx+ )+def test_condition_evaluation(self):from specify_cli.workflows.expressions import evaluate_conditionfrom specify_cli.workflows.base import StepContextdiff --git a/workflows/ARCHITECTURE.md b/workflows/ARCHITECTURE.mdindex 113545f33..477c0968a 100644--- a/workflows/ARCHITECTURE.md+++ b/workflows/ARCHITECTURE.md@@ -119,6 +119,7 @@ Workflow definitions use Jinja2-like `{{ expression }}` syntax for dynamic value| Filter: `join` | `{{ list \| join(', ') }}` | Join list elements || Filter: `contains` | `{{ text \| contains('sub') }}` | Substring/membership check || Filter: `map` | `{{ list \| map('attr') }}` | Extract attribute from each item |+| Filter: `from_json` | `{{ steps.emit.output.stdout \| from_json }}` | Parse a JSON string into a typed value (raises on invalid JSON) |**Single expressions** (`{{ expr }}` only) return typed values. **Mixed templates** (`"text {{ expr }} more"`) return interpolated strings.diff --git a/workflows/README.md b/workflows/README.mdindex 09a85617c..966e2d390 100644--- a/workflows/README.md+++ b/workflows/README.md@@ -332,7 +332,7 @@ condition: "{{ steps.run-tests.output.exit_code != 0 }}"message: "{{ status | default('pending') }}"```-Supported filters: `default`, `join`, `contains`, `map`.+Supported filters: `default`, `join`, `contains`, `map`, `from_json`.### Runtime Context