Python HCL2 Parser

Warnings

• breaking Starting with version 8.0.0, the `hcl2.load()` and `hcl2.loads()` functions now return a list of dictionaries instead of a single dictionary. This change better represents HCL2's top-level block structure.
  Fix: Update your code to iterate over the returned list or access elements by index. For example, `hcl2.loads(s)[0]` if you expect a single top-level block, or iterate `for block in hcl2.loads(s): ...`.
• gotcha While `python-hcl2` offers robust parsing, HCL2's dynamic features like interpolation (`${...}`), template directives (`%{if ...}`), and complex expressions can still lead to parsing nuances. Edge cases may not always be perfectly represented as standard Python data structures or round-trip identically.
  Fix: Consult the 'Limitations' section in the official documentation for known quirks. Thoroughly test parsing and serialization with your specific HCL2 configurations, especially those with advanced interpolation or conditional logic, to ensure expected behavior.
• gotcha Round-tripping (parsing HCL2 to Python then serializing back to HCL2) might not preserve original formatting, comments, or all subtle syntactic nuances present in the source HCL2 file. While v8 significantly improved bidirectional conversion, a perfect byte-for-byte fidelity is not guaranteed.
  Fix: If exact HCL2 formatting preservation is critical (e.g., for version control systems comparing files), consider using specialized HCL2 formatting tools externally or validate the output of `hcl2.dumps()` carefully. For programmatic manipulation where logical correctness is paramount, `hcl2.dumps()` is generally reliable.

Install

• pip install python-hcl2 Install latest version

Imports

• load

  import hcl2
  parsed_data = hcl2.load(file_object)

  While 'hcl2.parser' exists, the primary and recommended entry points are directly from the top-level 'hcl2' module.
• loads

  import hcl2
  parsed_data = hcl2.loads(hcl2_string)

  The 'loads' function is used for parsing HCL2 strings directly.
• dumps

  import hcl2
  hcl2_string = hcl2.dumps(python_dict_list)

  Introduced in v8 for serializing Python data back to HCL2 strings.

Quickstart

This quickstart demonstrates parsing an HCL2 configuration string using `hcl2.loads()` and then serializing the resulting Python list of dictionaries back into an HCL2 string using `hcl2.dumps()`. It highlights the v8 breaking change where parsing now returns a list of dictionaries.

import hcl2
import json

hcl2_config = '''
resource "aws_s3_bucket" "example" {
  bucket = "my-unique-bucket-name"
  acl    = "private"

  tags = {
    Environment = "Development"
    Project     = "MyApp"
  }
}

variable "region" {
  description = "AWS region"
  type        = string
  default     = "us-east-1"
}
'''

# Parse the HCL2 string
parsed_data = hcl2.loads(hcl2_config)

# Print the parsed data (v8 returns a list of dictionaries)
print("--- Parsed Data (Python List of Dicts) ---")
print(json.dumps(parsed_data, indent=2))

# Accessing specific blocks (example: the first resource block)
if parsed_data and 'resource' in parsed_data[0]:
    resource_block = parsed_data[0]['resource']['aws_s3_bucket']['example']
    print("\n--- Extracted Resource Block ---")
    print(json.dumps(resource_block, indent=2))

# Serialize back to HCL2 (v8 feature)
recreated_hcl2 = hcl2.dumps(parsed_data)
print("\n--- Recreated HCL2 ---")
print(recreated_hcl2)