0
# Terraformpy
1
2
A Python library and command line tool that enables developers to generate Terraform JSON configurations using full Python programming capabilities instead of HashiCorp Configuration Language (HCL). Terraformpy provides a declarative API for creating Terraform resources, providers, variables, outputs, modules, and data sources through Python classes, with support for advanced features like resource interpolation, backend configuration, provider aliasing, and resource collections.
3
4
## Package Information
5
6
- **Package Name**: terraformpy
7
- **Language**: Python
8
- **Installation**: `pip install terraformpy`
9
10
## Core Imports
11
12
```python
13
import terraformpy
14
```
15
16
Most common usage imports:
17
18
```python
19
from terraformpy import Resource, Data, Provider, Variable, Output, Module, Terraform
20
from terraformpy import compile, reset
21
```
22
23
For resource collections:
24
25
```python
26
from terraformpy import ResourceCollection, Variant
27
```
28
29
For helper utilities:
30
31
```python
32
from terraformpy.helpers import relative_file, relative_path
33
```
34
35
For AWS-specific hooks:
36
37
```python
38
from terraformpy.hooks.aws import install_aws_security_group_attributes_as_blocks_hook
39
from terraformpy.hooks.aws import fill_in_optional_aws_security_group_rules_attrs
40
```
41
42
## Basic Usage
43
44
```python
45
from terraformpy import Resource, Variable, Output, Provider, compile
46
47
# Define variables
48
env = Variable('environment', default='dev')
49
instance_type = Variable('instance_type', default='t3.micro')
50
51
# Configure provider
52
provider = Provider('aws', region='us-west-2')
53
54
# Create resources
55
web_server = Resource('aws_instance', 'web_server',
56
instance_type=instance_type, # Variables are used directly
57
ami='ami-12345678',
58
tags={'Name': 'WebServer-${var.environment}'} # Terraform interpolation syntax
59
)
60
61
# Define outputs
62
Output('instance_id', value=web_server.id)
63
Output('public_ip', value=web_server.public_ip)
64
65
# Compile to Terraform JSON
66
terraform_config = compile()
67
print(terraform_config)
68
69
# Reset for next configuration
70
reset()
71
```
72
73
## Architecture
74
75
Terraformpy uses a registration-based architecture with three key components:
76
77
- **TFObject Registry**: Global registry that tracks all created Terraform objects for compilation
78
- **Hook System**: Extensible transformation system that allows modification of objects during compilation
79
- **Interpolation Engine**: Automatic generation of Terraform interpolation syntax (`${resource.attribute}`) from Python attribute access
80
81
This design enables declarative Python code to generate complex Terraform configurations while maintaining the benefits of Python's programming environment, including variables, loops, conditionals, and modules.
82
83
## Capabilities
84
85
### Core Terraform Objects
86
87
Essential Terraform object types including resources, data sources, providers, variables, outputs, modules, and terraform configuration blocks. These form the foundation of any Terraform configuration.
88
89
```python { .api }
90
class Resource(type: str, name: str, **kwargs): ...
91
class Data(type: str, name: str, **kwargs): ...
92
class Provider(name: str, **kwargs): ...
93
class Variable(name: str, **kwargs): ...
94
class Output(name: str, **kwargs): ...
95
class Module(name: str, **kwargs): ...
96
class Terraform(**kwargs): ...
97
```
98
99
[Core Objects](./core-objects.md)
100
101
### Resource Collections
102
103
Framework for creating reusable, parameterized groups of resources that can be instantiated with different configurations. Supports environment-specific variants and inheritance patterns.
104
105
```python { .api }
106
class ResourceCollection(schematics.Model):
107
def create_resources(self): ...
108
109
class Variant(name: str): ...
110
```
111
112
[Resource Collections](./resource-collections.md)
113
114
### Helper Utilities
115
116
Utilities for working with file paths and local resources in Terraform configurations, enabling relative path references that work correctly regardless of where the Python script is executed.
117
118
```python { .api }
119
def relative_file(filename: str, _caller_depth: int = 1) -> str: ...
120
def relative_path(path: str, _caller_depth: int = 1) -> str: ...
121
```
122
123
[Helper Utilities](./helpers.md)
124
125
### Compilation and Management
126
127
Functions for compiling registered Terraform objects to JSON and managing the global object registry, including hook system for extending functionality.
128
129
```python { .api }
130
def compile() -> dict: ...
131
def reset() -> None: ...
132
133
# Hook system
134
TFObject.add_hook(object_type: str, hook_function: Callable) -> None
135
```
136
137
[Compilation and Hooks](./compilation-hooks.md)
138
139
### AWS Hooks and Utilities
140
141
AWS-specific hooks and utilities for handling AWS resource configurations and provider quirks, including security group rule transformations and other AWS-specific fixes.
142
143
```python { .api }
144
def install_aws_security_group_attributes_as_blocks_hook() -> None: ...
145
def fill_in_optional_aws_security_group_rules_attrs(object_id: str, attrs: dict) -> dict: ...
146
147
SECURITY_GROUP_RULE_OPTIONAL_ATTRS: tuple
148
```
149
150
[AWS Hooks](./aws-hooks.md)
151
152
### Command Line Interface
153
154
CLI tool for processing Python files containing Terraform configurations and generating JSON output files compatible with Terraform tooling.
155
156
```bash { .api }
157
terraformpy [options]
158
```
159
160
[CLI Interface](./cli.md)
161
162
## Types
163
164
Core types used throughout the terraformpy API:
165
166
```python { .api }
167
class TFObject:
168
"""Base class for all Terraform objects with compilation and hook support."""
169
170
@classmethod
171
def compile() -> str:
172
"""Compile all registered objects to Terraform JSON."""
173
174
@classmethod
175
def reset() -> None:
176
"""Clear all registered objects from the registry."""
177
178
@classmethod
179
def add_hook(object_type: str, hook_function: Callable[[str, dict], dict]) -> None:
180
"""Add a transformation hook for objects of the specified type."""
181
182
class DuplicateKey(str):
183
"""
184
String subclass for handling duplicate JSON keys in provider configurations.
185
186
Allows the same key to appear multiple times in JSON dictionaries, which is
187
required for Terraform provider configurations but technically invalid in JSON.
188
Uses a counter-based hash to maintain insertion order and uniqueness.
189
"""
190
191
def __new__(cls, key: str) -> DuplicateKey:
192
"""Create a duplicate-safe key from a string."""
193
194
class OrderedDict(schematics.types.compound.DictType):
195
"""
196
Schematics DictType that preserves key insertion order.
197
198
Maintains the order in which keys are added to the dictionary,
199
which is important for consistent Terraform JSON generation.
200
"""
201
202
def convert(self, value, context=None):
203
"""Convert value while maintaining key insertion order."""
204
205
class TypedObjectAttr(str):
206
"""
207
String subclass that generates Terraform interpolation syntax for resource attributes.
208
209
Automatically creates Terraform interpolation expressions like ${resource.attribute}
210
when accessing attributes on Resource and Data objects.
211
"""
212
213
def __init__(self, terraform_name: str, attr_name: str):
214
"""
215
Create interpolation reference like ${resource_type.name.attribute}.
216
217
Parameters:
218
- terraform_name: Full Terraform object name (e.g., 'aws_instance.web')
219
- attr_name: Attribute name (e.g., 'id', 'public_ip')
220
"""
221
222
def __getitem__(self, key: str) -> TypedObjectAttr:
223
"""Support array/map indexing: resource.attribute[key]."""
224
225
def __getattr__(self, name: str) -> TypedObjectAttr:
226
"""Support nested attribute access: resource.attribute.nested."""
227
```