Add support for 'array' input from JSON data.

Author: kpfleming

README.md

@@ -255,7 +255,13 @@ JSON data input format.
 
 #### Options
 
-This format does not support any options.
+* `array-name`: accepts a single string (e.g. `array-name=foo`), which
+  must be a valid Python identifier and not a Python keyword. If this
+  option is specified, and the JSON data provided is an `array`
+  (sequence, list), the specified name will be used to make the data
+  available to the Jinja2 template. Errors will be generated if
+  `array` data is provided and this option is not specified, or if
+  this option is specified and the data provided is an `object`.
 
 #### Usage
 

changelog.d/15.adding.md

@@ -0,0 +1 @@
+Added support for 'array' data in JSON-format input.

src/jinjanator/formats.py

@@ -59,10 +59,28 @@ def as_dict(self) -> Mapping[str, Any]:
 class JSONFormat:
     name = "json"
     suffixes: Iterable[str] | None = (".json",)
-    option_names: Iterable[str] | None = ()
+    option_names: Iterable[str] | None = "array-name"
 
     def __init__(self, options: Iterable[str] | None) -> None:
-        pass
+        self.array_name: str | None = None
+        if options:
+            for option in options:
+                try:
+                    opt, val = option.split("=")
+                except ValueError as exc:
+                    raise FormatOptionValueError(
+                        self, option, "", "contains more than one '='"
+                    ) from exc
+
+                if not val.isidentifier():
+                    raise FormatOptionValueError(
+                        self, opt, val, "is not a valid Python identifier"
+                    )
+
+                if keyword.iskeyword(val):
+                    raise FormatOptionValueError(self, opt, val, "is a Python keyword")
+
+                self.array_name = val
 
     def parse(self, data_string: str) -> Mapping[str, Any]:
         """JSON data input format.
@@ -85,13 +103,28 @@ def parse(self, data_string: str) -> Mapping[str, Any]:
         $ cat data.json | j2 --format=ini config.j2
         """
 
-        context = json.loads(data_string)
+        try:
+            context = json.loads(data_string)
+        except json.decoder.JSONDecodeError as exc:
+            msg = "JSON input is neither an object nor an array"
+            raise TypeError(msg) from exc
+
+        if isinstance(context, dict):
+            if self.array_name:
+                raise FormatOptionUnsupportedError(
+                    self,
+                    "array-name",
+                    "cannot be used with object (dictionary) input",
+                )
+
+            return context
 
-        if not isinstance(context, dict):
-            msg = "JSON input does not contain an object (dictionary)"
-            raise TypeError(msg)
+        if not self.array_name:
+            raise FormatOptionUnsupportedError(
+                self, "array-name", "must be specified for array (list) input"
+            )
 
-        return context
+        return {self.array_name: context}
 
 
 class YAMLFormat:

tests/test_invalid_data.py

@@ -10,14 +10,14 @@
 
 
 def test_invalid_json(make_file_pair: FilePairFactory) -> None:
-    files = make_file_pair("", '["one", "two"]', "json")
+    files = make_file_pair("", "midge", "json")
 
-    with pytest.raises(TypeError, match="JSON input does not contain an object"):
+    with pytest.raises(TypeError, match="JSON input is neither an object nor an array"):
         assert render_file(files, [])
 
 
 def test_invalid_yaml(make_file_pair: FilePairFactory) -> None:
-    files = make_file_pair("", "-one\n-two", "yaml")
+    files = make_file_pair("", "midge", "yaml")
 
     with pytest.raises(TypeError, match="YAML input is neither a mapping nor a sequence"):
         assert render_file(files, [])

tests/test_json_input.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import jinjanator_plugins
+import pytest
+
+from . import (
+    FilePairFactory,
+    render_file,
+)
+
+
+def test_mapping_normal(make_file_pair: FilePairFactory) -> None:
+    files = make_file_pair("{{ foo }}", '{"foo": "bar"}', "json")
+
+    assert "bar" == render_file(files, [])
+
+
+def test_mapping_with_array_name_option(make_file_pair: FilePairFactory) -> None:
+    files = make_file_pair("{{ foo }}", '{"foo": "bar"}', "json")
+
+    with pytest.raises(jinjanator_plugins.FormatOptionUnsupportedError):
+        assert render_file(files, ["--format-option", "array-name=seq"])
+
+
+def test_array_normal(make_file_pair: FilePairFactory) -> None:
+    files = make_file_pair("{{ seq[0] }}", "[1,2,3]", "json")
+
+    assert "1" == render_file(files, ["--format-option", "array-name=seq"])
+
+
+def test_array_without_array_name_option(make_file_pair: FilePairFactory) -> None:
+    files = make_file_pair("{{ seq[0] }}", "[1,2,3]", "json")
+
+    with pytest.raises(jinjanator_plugins.FormatOptionUnsupportedError):
+        assert render_file(files, [])
+
+
+def test_array_invalid_name(make_file_pair: FilePairFactory) -> None:
+    files = make_file_pair("{{ seq[0] }}", "[1,2,3]", "json")
+
+    with pytest.raises(jinjanator_plugins.FormatOptionValueError):
+        render_file(files, ["--format-option", "array-name=334seq"])
+
+
+def test_array_invalid_value(make_file_pair: FilePairFactory) -> None:
+    files = make_file_pair("{{ seq[0] }}", "[1,2,3]", "json")
+
+    with pytest.raises(jinjanator_plugins.FormatOptionValueError):
+        render_file(files, ["--format-option", "array-name=abc=def"])
+
+
+def test_array_keyword_name(make_file_pair: FilePairFactory) -> None:
+    files = make_file_pair("{{ seq[0] }}", "[1,2,3]", "json")
+
+    with pytest.raises(jinjanator_plugins.FormatOptionValueError):
+        render_file(files, ["--format-option", "array-name=raise"])