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
```