python-hcl2 7.0.0__tar.gz → 7.1.0__tar.gz

python_hcl2-7.1.0/.github/ISSUE_TEMPLATE/hcl2-parsing-error.md

@@ -0,0 +1,32 @@
+---
+name: HCL2 parsing error
+about: Template for reporting a bug related to parsing HCL2 code
+title: ''
+labels: bug
+assignees: kkozik-amplify
+
+---
+
+**Describe the bug**
+
+A clear and concise description of what the bug is.
+
+**Software:**
+ - OS: [macOS / Windows / Linux]
+ - Python version (e.g. 3.9.21)
+ - python-hcl2 version (e.g. 7.0.0)
+
+**Snippet of HCL2 code causing the unexpected behaviour:**
+```terraform
+locals {
+  foo = "bar"
+}
+```
+**Expected behavior**
+
+A clear and concise description of what you expected to happen, e.g. python dictionary or JSON you expected to receive as a result of parsing.
+
+**Exception traceback (if applicable)**:
+
+```
+```

{python_hcl2-7.0.0 → python_hcl2-7.1.0}/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## \[Unreleased\]
+
+- Nothing yet
+
+## \[7.1.0\] - 2025-04-10
+
+### Added
+
+- `hcl2.builder.Builder` - nested blocks support ([#214](https://github.com/amplify-education/python-hcl2/pull/214))
+
+### Fixed
+
+- Issue parsing parenthesesed identifier (reference) as an object key ([#212](https://github.com/amplify-education/python-hcl2/pull/212))
+- Issue discarding empty lists when transforming python dictionary into Lark Tree ([#216](https://github.com/amplify-education/python-hcl2/pull/216))
+
+## \[7.0.1\] - 2025-03-31
+
+### Fixed
+
+- Issue parsing dot-accessed attribute as an object key ([#209](https://github.com/amplify-education/python-hcl2/pull/209))
+
 ## \[7.0.0\] - 2025-03-27
 
 ### Added

{python_hcl2-7.0.0/python_hcl2.egg-info → python_hcl2-7.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hcl2
-Version: 7.0.0
+Version: 7.1.0
 Summary: A parser for HCL2
 Author-email: Amplify Education <github@amplify.com>
 License: MIT

python_hcl2-7.1.0/hcl2/builder.py

@@ -0,0 +1,86 @@
+"""A utility class for constructing HCL documents from Python code."""
+from typing import List, Optional
+
+from collections import defaultdict
+
+from hcl2.const import START_LINE_KEY, END_LINE_KEY
+
+
+class Builder:
+    """
+    The `hcl2.Builder` class produces a dictionary that should be identical to the
+    output of `hcl2.load(example_file, with_meta=True)`. The `with_meta` keyword
+    argument is important here. HCL "blocks" in the Python dictionary are
+    identified by the presence of `__start_line__` and `__end_line__` metadata
+    within them. The `Builder` class handles adding that metadata. If that metadata
+    is missing, the `hcl2.reconstructor.HCLReverseTransformer` class fails to
+    identify what is a block and what is just an attribute with an object value.
+    """
+
+    def __init__(self, attributes: Optional[dict] = None):
+        self.blocks: dict = defaultdict(list)
+        self.attributes = attributes or {}
+
+    def block(
+        self,
+        block_type: str,
+        labels: Optional[List[str]] = None,
+        __nested_builder__: Optional["Builder"] = None,
+        **attributes
+    ) -> "Builder":
+        """Create a block within this HCL document."""
+
+        if __nested_builder__ is self:
+            raise ValueError(
+                "__nested__builder__ cannot be the same instance as instance this method is called on"
+            )
+
+        labels = labels or []
+        block = Builder(attributes)
+
+        # store the block in the document
+        self.blocks[block_type].append((labels.copy(), block, __nested_builder__))
+
+        return block
+
+    def build(self):
+        """Return the Python dictionary for this HCL document."""
+        body = defaultdict(list)
+
+        body.update(
+            {
+                START_LINE_KEY: -1,
+                END_LINE_KEY: -1,
+                **self.attributes,
+            }
+        )
+
+        for block_type, blocks in self.blocks.items():
+
+            for labels, block_builder, nested_blocks in blocks:
+                # build the sub-block
+                block = block_builder.build()
+
+                if nested_blocks:
+                    self._add_nested_blocks(block, nested_blocks)
+
+                # apply any labels
+                for label in reversed(labels):
+                    block = {label: block}
+
+                # store it in the body
+                body[block_type].append(block)
+
+        return body
+
+    def _add_nested_blocks(
+        self, block: dict, nested_blocks_builder: "Builder"
+    ) -> "dict":
+        """Add nested blocks defined within another `Builder` instance to the `block` dictionary"""
+        nested_block = nested_blocks_builder.build()
+        for key, value in nested_block.items():
+            if key not in (START_LINE_KEY, END_LINE_KEY):
+                if key not in block.keys():
+                    block[key] = []
+                block[key].extend(value)
+        return block

python_hcl2-7.1.0/hcl2/const.py

@@ -0,0 +1,4 @@
+"""Module for various constants used across the library"""
+
+START_LINE_KEY = "__start_line__"
+END_LINE_KEY = "__end_line__"

{python_hcl2-7.0.0 → python_hcl2-7.1.0}/hcl2/hcl2.lark

@@ -38,6 +38,8 @@ PLUS : "+"
 LPAR : "("
 RPAR : ")"
 COMMA : ","
+DOT : "."
+COLON : ":"
 
 expr_term : LPAR new_line_or_comment? expression new_line_or_comment? RPAR
             | float_lit
@@ -73,9 +75,9 @@ EQ : /[ \t]*=(?!=|>)/
 
 tuple : "[" (new_line_or_comment* expression new_line_or_comment* ",")* (new_line_or_comment* expression)? new_line_or_comment* "]"
 object : "{" new_line_or_comment? (new_line_or_comment* (object_elem | (object_elem COMMA)) new_line_or_comment*)* "}"
-object_elem : object_elem_key ( EQ | ":") expression
-object_elem_key : float_lit | int_lit | identifier | STRING_LIT
-
+object_elem : LPAR? object_elem_key RPAR? ( EQ | COLON ) expression
+object_elem_key : float_lit | int_lit | identifier | STRING_LIT | object_elem_key_dot_accessor
+object_elem_key_dot_accessor : identifier (DOT identifier)+
 
 heredoc_template : /<<(?P<heredoc>[a-zA-Z][a-zA-Z0-9._-]+)\n?(?:.|\n)*?\n\s*(?P=heredoc)\n/
 heredoc_template_trim : /<<-(?P<heredoc_trim>[a-zA-Z][a-zA-Z0-9._-]+)\n?(?:.|\n)*?\n\s*(?P=heredoc_trim)\n/

{python_hcl2-7.0.0 → python_hcl2-7.1.0}/hcl2/reconstructor.py

@@ -10,6 +10,8 @@ from lark.lexer import Token, PatternStr, TerminalDef
 from lark.reconstruct import Reconstructor
 from lark.tree_matcher import is_discarded_terminal
 from lark.visitors import Transformer_InPlace
+
+from hcl2.const import START_LINE_KEY, END_LINE_KEY
 from hcl2.parser import reconstruction_parser
 
 
@@ -395,46 +397,41 @@ class HCLReverseTransformer:
 
         return True
 
+    @classmethod
+    def _unwrap_interpolation(cls, value: str) -> str:
+        if cls._is_string_wrapped_tf(value):
+            return value[2:-1]
+        return value
+
     def _newline(self, level: int, count: int = 1) -> Tree:
         return Tree(
             Token("RULE", "new_line_or_comment"),
             [Token("NL_OR_COMMENT", f"\n{'  ' * level}") for _ in range(count)],
         )
 
-    # rules: the value of a block is always an array of dicts,
-    # the key is the block type
-    def _list_is_a_block(self, value: list) -> bool:
-        for obj in value:
-            if not self._dict_is_a_block(obj):
-                return False
-
-        return True
-
-    def _dict_is_a_block(self, sub_obj: Any) -> bool:
-        # if the list doesn't contain dictionaries, it's not a block
-        if not isinstance(sub_obj, dict):
-            return False
+    def _is_block(self, value: Any) -> bool:
+        if isinstance(value, dict):
+            block_body = value
+            if (
+                START_LINE_KEY in block_body.keys()
+                or END_LINE_KEY in block_body.keys()
+            ):
+                return True
 
-        # if the sub object has "start_line" and "end_line" metadata,
-        # the block itself is unlabeled, but it is a block
-        if "__start_line__" in sub_obj.keys() or "__end_line__" in sub_obj.keys():
-            return True
+            try:
+                # if block is labeled, actual body might be nested
+                # pylint: disable=W0612
+                block_label, block_body = next(iter(value.items()))
+            except StopIteration:
+                # no more potential labels = nothing more to check
+                return False
 
-        # if the objects in the array have no metadata and more than 2 keys and
-        # no metadata, it's just an array of objects, not a block
-        if len(list(sub_obj)) != 1:
-            return False
+            return self._is_block(block_body)
 
-        # if the sub object has a single string key whose value is an object,
-        # it _could_ be a labeled block... but we'd have to check if the sub
-        # object is a block (recurse)
-        label = list(sub_obj)[0]
-        sub_sub_obj = sub_obj[label]
-        if self._dict_is_a_block(sub_sub_obj):
-            return True
+        if isinstance(value, list):
+            if len(value) > 0:
+                return self._is_block(value[0])
 
-        # if the objects in the array have a single key whose child is not a
-        # block, the array is just an array of objects, not a block
         return False
 
     def _calculate_block_labels(self, block: dict) -> Tuple[List[str], dict]:
@@ -448,8 +445,8 @@ class HCLReverseTransformer:
 
         # __start_line__ and __end_line__ metadata are not labels
         if (
-            "__start_line__" in potential_body.keys()
-            or "__end_line__" in potential_body.keys()
+            START_LINE_KEY in potential_body.keys()
+            or END_LINE_KEY in potential_body.keys()
         ):
             return [curr_label], potential_body
 
@@ -457,6 +454,7 @@ class HCLReverseTransformer:
         next_label, block_body = self._calculate_block_labels(potential_body)
         return [curr_label] + next_label, block_body
 
+    # pylint:disable=R0914
     def _transform_dict_to_body(self, hcl_dict: dict, level: int) -> Tree:
         # we add a newline at the top of a body within a block, not the root body
         # >2 here is to ignore the __start_line__ and __end_line__ metadata
@@ -467,14 +465,14 @@ class HCLReverseTransformer:
 
         # iterate through each attribute or sub-block of this block
         for key, value in hcl_dict.items():
-            if key in ["__start_line__", "__end_line__"]:
+            if key in [START_LINE_KEY, END_LINE_KEY]:
                 continue
 
             # construct the identifier, whether that be a block type name or an attribute key
             identifier_name = self._name_to_identifier(key)
 
             # first, check whether the value is a "block"
-            if isinstance(value, list) and self._list_is_a_block(value):
+            if self._is_block(value):
                 for block_v in value:
                     block_labels, block_body_dict = self._calculate_block_labels(
                         block_v
@@ -493,7 +491,12 @@ class HCLReverseTransformer:
                         [identifier_name] + block_label_tokens + [block_body],
                     )
                     children.append(block)
-                    children.append(self._newline(level, count=2))
+                    # add empty line after block
+                    new_line = self._newline(level - 1)
+                    # add empty line with indentation for next element in the block
+                    new_line.children.append(self._newline(level).children[0])
+
+                    children.append(new_line)
 
             # if the value isn't a block, it's an attribute
             else:
@@ -556,10 +559,11 @@ class HCLReverseTransformer:
 
             # iterate through the items and add them to the object
             for i, (k, dict_v) in enumerate(value.items()):
-                if k in ["__start_line__", "__end_line__"]:
+                if k in [START_LINE_KEY, END_LINE_KEY]:
                     continue
 
                 value_expr_term = self._transform_value_to_expr_term(dict_v, level + 1)
+                k = self._unwrap_interpolation(k)
                 elements.append(
                     Tree(
                         Token("RULE", "object_elem"),

{python_hcl2-7.0.0 → python_hcl2-7.1.0}/hcl2/transformer.py

@@ -98,15 +98,21 @@ class DictTransformer(Transformer):
     def object_elem(self, args: List) -> Dict:
         # This returns a dict with a single key/value pair to make it easier to merge these
         # into a bigger dict that is returned by the "object" function
-        key = self.strip_quotes(str(args[0].children[0]))
-        if len(args) == 3:
-            value = args[2]
+        if args[0] == Token("LPAR", "("):
+            key = self.strip_quotes(str(args[1].children[0]))
+            key = f"({key})"
+            key = self.to_string_dollar(key)
+            value = args[4]
         else:
-            value = args[1]
+            key = self.strip_quotes(str(args[0].children[0]))
+            value = args[2]
 
         value = self.to_string_dollar(value)
         return {key: value}
 
+    def object_elem_key_dot_accessor(self, args: List) -> str:
+        return "".join(args)
+
     def object(self, args: List) -> Dict:
         args = self.strip_new_line_tokens(args)
         result: Dict[str, Any] = {}

{python_hcl2-7.0.0 → python_hcl2-7.1.0}/hcl2/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '7.0.0'
-__version_tuple__ = version_tuple = (7, 0, 0)
+__version__ = version = '7.1.0'
+__version_tuple__ = version_tuple = (7, 1, 0)

{python_hcl2-7.0.0 → python_hcl2-7.1.0/python_hcl2.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hcl2
-Version: 7.0.0
+Version: 7.1.0
 Summary: A parser for HCL2
 Author-email: Amplify Education <github@amplify.com>
 License: MIT

{python_hcl2-7.0.0 → python_hcl2-7.1.0}/python_hcl2.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ test-requirements.txt
 tox.ini
 tree-to-hcl2-reconstruction.md
 .github/CODEOWNERS
+.github/ISSUE_TEMPLATE/hcl2-parsing-error.md
 .github/workflows/codeql-analysis.yml
 .github/workflows/pr_check.yml
 .github/workflows/publish.yml
@@ -23,6 +24,7 @@ hcl2/__init__.py
 hcl2/__main__.py
 hcl2/api.py
 hcl2/builder.py
+hcl2/const.py
 hcl2/hcl2.lark
 hcl2/parser.py
 hcl2/py.typed

python_hcl2-7.0.0/hcl2/builder.py

@@ -1,63 +0,0 @@
-"""A utility class for constructing HCL documents from Python code."""
-
-from typing import List, Optional
-
-
-class Builder:
-    """
-    The `hcl2.Builder` class produces a dictionary that should be identical to the
-    output of `hcl2.load(example_file, with_meta=True)`. The `with_meta` keyword
-    argument is important here. HCL "blocks" in the Python dictionary are
-    identified by the presence of `__start_line__` and `__end_line__` metadata
-    within them. The `Builder` class handles adding that metadata. If that metadata
-    is missing, the `hcl2.reconstructor.HCLReverseTransformer` class fails to
-    identify what is a block and what is just an attribute with an object value.
-    """
-
-    def __init__(self, attributes: Optional[dict] = None):
-        self.blocks: dict = {}
-        self.attributes = attributes or {}
-
-    def block(
-        self, block_type: str, labels: Optional[List[str]] = None, **attributes
-    ) -> "Builder":
-        """Create a block within this HCL document."""
-        labels = labels or []
-        block = Builder(attributes)
-
-        # initialize a holder for blocks of that type
-        if block_type not in self.blocks:
-            self.blocks[block_type] = []
-
-        # store the block in the document
-        self.blocks[block_type].append((labels.copy(), block))
-
-        return block
-
-    def build(self):
-        """Return the Python dictionary for this HCL document."""
-        body = {
-            "__start_line__": -1,
-            "__end_line__": -1,
-            **self.attributes,
-        }
-
-        for block_type, blocks in self.blocks.items():
-
-            # initialize a holder for blocks of that type
-            if block_type not in body:
-                body[block_type] = []
-
-            for labels, block_builder in blocks:
-                # build the sub-block
-                block = block_builder.build()
-
-                # apply any labels
-                labels.reverse()
-                for label in labels:
-                    block = {label: block}
-
-                # store it in the body
-                body[block_type].append(block)
-
-        return body