phcl 0.5.3

Python-based Infrastructure as Code (IaC) tool for dynamic infrastructure workflows.

PHCL

PHCL provides an authoring and generation layer for HCL-based tools such as Terraform, OpenTofu, and Packer.

PHCL does not assume a full project rewrite.
You can keep your existing Terraform/OpenTofu codebase and use PHCL only for a single .tf file that needs to be parameterized or generated from external data.

PHCL code is not an application framework or runtime model. There is no entry point.

PHCL .py files are rendered directly and independently into the corresponding .tf files, so they can be mixed with regular HCL files inside the same project:

src/network.py → src/network.tf

HCL declarations are written as Python classes. The source stays close to the shape of HCL while adding composition, dynamic generation, and integration with Python data and logic.

Example

class Logs(Resource["aws_s3_bucket"]):
    bucket = "app-logs"
    force_destroy = True
    tags = {
        "Name": "logs",
        "ManagedBy": "PHCL",
    }


class BucketId(Output):
    value = Logs._.id

renders as native HCL:

resource "aws_s3_bucket" "logs" {
  bucket = "app-logs"
  force_destroy = true
  tags = {
    Name = "logs"
    ManagedBy = "PHCL"
  }
}

output "bucket_id" {
  value = aws_s3_bucket.logs.id
}

Use Cases

PHCL is useful when HCL is derived from project data rather than written directly: RBAC rules, users, roles, regions, environments, inventories, service definitions, or other source-of-truth records. When used alongside an existing Python project, PHCL can share data, constants, validation, and project logic, adapting generated configuration to the application it belongs to.

For example, repeated declarations can be generated from normal Python data:

BUCKETS = {
    "logs": {"bucket": "app-logs"},
    "assets": {"bucket": "app-assets"},
}


@generate(BUCKETS)
class Bucket(Resource["aws_s3_bucket"]):
    bucket = this.value["bucket"]
    tags = {"Name": this.key}

PHCL also fits incremental adoption in existing HCL projects: generate one file, one subtree, or one environment at a time, while the output remains plain HCL that can live next to hand-written configuration.

CLI

Install PHCL:

pip install phcl

Install PHCL with the Terraform dialect:

pip install 'phcl[terraform]'

Build one file or a source tree:

ENV=dev phcl build src --out-dir envs/dev/

Example output:

==> build src
  write src/backend.py -> envs/dev/backend.tf
  write src/database.py -> envs/dev/database.tf
  write src/network.py -> envs/dev/network.tf
  write src/security.py -> envs/dev/security.tf

==> done in 0.06s
  13 written, 0 skipped, 0 failed

Documentation

• Documentation