tfparse

0.6.19.post1 · active · verified Fri Apr 17

tfparse is a Python library providing a fast, robust parser for HCL (HashiCorp Configuration Language) and Terraform files. It leverages a Go extension for its core parsing capabilities, making it efficient for use cases like security scanning (e.g., AquaSecurity defsec). The library is actively maintained with frequent minor releases, often on a weekly or bi-weekly cadence, reflecting ongoing improvements and bug fixes.

Common errors

```
KeyError: '<some_reference_path>'
```
cause Your code is attempting to access a Terraform reference using an outdated path or structure, likely due to the breaking change in how `tfparse` tracks references since v0.6.15.

fix Update your code to align with the new reference tracking behavior introduced in `tfparse` v0.6.15. Consult the `c7n-left` project's changes for guidance on adapting to the new structure.
```
tfparse.errors.ParseError: Block iteration failed due to unknown value
```
cause This error occurs when `tfparse` encounters dynamic blocks (e.g., `for_each`) or expressions that depend on values that are not resolvable during static parsing (i.e., 'unknown').

fix If possible, ensure all variables and expressions in dynamic blocks are resolvable within your parsing context. Consider upgrading to `tfparse >= 0.6.18` for improved handling of partially unknown `for_each` blocks.
```
json.decoder.JSONDecodeError: Expecting value: line X column Y (char Z)
```
cause You are attempting to parse a string from `tfparse` as JSON, but the string is malformed or contains unresolved HCL references, preventing it from being valid JSON.

fix Verify the HCL source for the string value; ensure it's a valid and fully resolved JSON string. Upgrade to `tfparse >= 0.6.19` to benefit from fixes related to how `tfparse` handles unresolved JSON strings.

Warnings

breaking Version 0.6.15 introduced a breaking change to internal reference-tracking, specifically to support multiple references within a single block. Code that directly manipulates or relies on the structure of tracked references will need updating.
Fix: Review the reference-tracking changes (e.g., in the `c7n-left` project, linked in release notes) and adapt your code to the new data structure for references.
gotcha Parsing configurations with dynamic blocks (`for_each`) or values that are not 'wholly known' (e.g., runtime outputs, sensitive data) can lead to unexpected parsing behavior or errors.
Fix: Upgrade to `tfparse >= 0.6.18` which includes fixes for handling partially unknown `for_each` blocks. Ensure that values required for static parsing are resolvable or handle potential `None`/`unknown` gracefully in your application logic.
gotcha HCL strings intended to be JSON, but containing unresolved references or malformed content, may result in `tfparse` returning non-valid JSON strings, leading to subsequent JSON parsing failures.
Fix: Ensure that any HCL string values intended to be JSON are fully resolved and syntactically correct at the time of parsing. Upgrade to `tfparse >= 0.6.19` which contains a fix for these `unresolved JSON strings`.

Install

pip install tfparse Install tfparse

Imports

parse
```
from tfparse import parse
```
load_from_path
```
from tfparse import load_from_path
```

Quickstart

Demonstrates parsing a Terraform configuration string and accessing structured data from the result. For parsing entire directories, use `tfparse.load_from_path`.

from tfparse import parse

# Example Terraform configuration as a string
terraform_config = """
resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-unique-bucket-name"
  acl    = "private"

  tags = {
    Environment = "Dev"
    Project     = "tfparse-example"
  }
}

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

try:
    # Parse the HCL configuration string
    parsed_data = parse(terraform_config)
    print("Successfully parsed Terraform configuration:")
    
    # Access some parsed data, e.g., the resource block
    s3_bucket = parsed_data.get("resource", {}).get("aws_s3_bucket", {}).get("my_bucket")
    if s3_bucket:
        print(f"  Resource 'aws_s3_bucket.my_bucket' found. Bucket name: {s3_bucket.get('bucket')}")
        print(f"  Tags: {s3_bucket.get('tags')}")

    # Access a variable block
    region_var = parsed_data.get("variable", {}).get("region")
    if region_var:
        print(f"  Variable 'region' default: {region_var.get('default')}")

except Exception as e:
    print(f"Error parsing configuration: {e}")

view raw JSON →