0
# Configuration
1
2
User configuration handling with defaults, file-based config, and runtime overrides for customizing cookiecutter behavior. The configuration system allows users to set default values, template abbreviations, and preferences that persist across cookiecutter sessions.
3
4
## Capabilities
5
6
### Configuration Loading
7
8
Load and merge user configuration from various sources with fallback to defaults.
9
10
```python { .api }
11
def get_user_config(config_file=None, default_config=False):
12
"""
13
Return user config as dict with various fallback options.
14
15
Parameters:
16
- config_file: str, optional - Path to user config file
17
- default_config: bool - Use default values rather than a config file
18
19
Returns:
20
dict - Configuration dictionary with merged settings
21
"""
22
23
def get_config(config_path):
24
"""
25
Retrieve config from specified path, returning config dict.
26
27
Parameters:
28
- config_path: str - Path to configuration file
29
30
Returns:
31
dict - Configuration dictionary from file
32
"""
33
```
34
35
### Configuration Merging
36
37
Merge configuration dictionaries with proper precedence handling.
38
39
```python { .api }
40
def merge_configs(default, overwrite):
41
"""
42
Recursively merge configuration dictionaries.
43
44
Parameters:
45
- default: dict - Default configuration values
46
- overwrite: dict - Configuration values to override defaults
47
48
Returns:
49
dict - Merged configuration dictionary
50
"""
51
```
52
53
## Configuration Constants
54
55
### Default Paths and Settings
56
57
```python { .api }
58
USER_CONFIG_PATH: str # Default user config file path (~/.cookiecutterrc)
59
60
BUILTIN_ABBREVIATIONS: dict # Built-in repository abbreviations
61
# Contains: {'gh': 'https://github.com/{0}.git', 'gl': 'https://gitlab.com/{0}.git', 'bb': 'https://bitbucket.org/{0}'}
62
63
DEFAULT_CONFIG: dict # Default configuration dictionary
64
```
65
66
## Configuration File Format
67
68
Cookiecutter supports YAML configuration files with the following structure:
69
70
```yaml
71
default_context:
72
full_name: "Your Name"
73
email: "you@example.com"
74
github_username: "yourusername"
75
76
cookiecutters_dir: "~/.cookiecutters"
77
78
abbreviations:
79
gh: https://github.com/{0}.git
80
gl: https://gitlab.com/{0}.git
81
bb: https://bitbucket.org/{0}
82
custom: https://mycustomrepo.com/{0}.git
83
84
replay_dir: "~/.cookiecutter_replay"
85
```
86
87
## Usage Examples
88
89
### Basic Configuration Loading
90
91
```python
92
from cookiecutter.config import get_user_config
93
94
# Load default user configuration
95
config = get_user_config()
96
97
# Load from specific config file
98
config = get_user_config(config_file='/path/to/config.yaml')
99
100
# Use built-in defaults only
101
config = get_user_config(default_config=True)
102
```
103
104
### Configuration Structure
105
106
The configuration dictionary contains these standard keys:
107
108
```python
109
{
110
'default_context': {
111
# Default values for template variables
112
'full_name': 'User Name',
113
'email': 'user@example.com'
114
},
115
'cookiecutters_dir': '/path/to/cookiecutters', # Template cache directory
116
'abbreviations': {
117
# Repository shortcuts
118
'gh': 'https://github.com/{}.git',
119
'custom': 'https://myrepo.com/{}.git'
120
},
121
'replay_dir': '/path/to/replay' # Replay file storage
122
}
123
```
124
125
### Custom Configuration
126
127
```python
128
from cookiecutter.config import get_user_config, merge_configs
129
130
# Load user config and merge with custom overrides
131
base_config = get_user_config()
132
custom_overrides = {
133
'default_context': {
134
'project_name': 'my-default-project',
135
'version': '0.1.0'
136
},
137
'cookiecutters_dir': '/custom/templates/path'
138
}
139
140
merged_config = merge_configs(base_config, custom_overrides)
141
```
142
143
### Working with Abbreviations
144
145
```python
146
from cookiecutter.config import BUILTIN_ABBREVIATIONS
147
from cookiecutter.repository import expand_abbreviations
148
149
# Use built-in abbreviations
150
print(BUILTIN_ABBREVIATIONS)
151
# {'gh': 'https://github.com/{0}.git', 'gl': 'https://gitlab.com/{0}.git', 'bb': 'https://bitbucket.org/{0}'}
152
153
# Expand abbreviation to full URL
154
config = get_user_config()
155
full_url = expand_abbreviations('gh:audreyfeldroy/cookiecutter-pypackage', config['abbreviations'])
156
# Returns: 'https://github.com/audreyfeldroy/cookiecutter-pypackage.git'
157
```
158
159
### Configuration File Management
160
161
```python
162
from cookiecutter.config import get_config
163
from cookiecutter.exceptions import ConfigDoesNotExistException
164
165
try:
166
# Load specific config file
167
config = get_config('/path/to/cookiecutter.yaml')
168
169
# Access configuration values
170
default_author = config.get('default_context', {}).get('full_name', 'Unknown')
171
template_dir = config.get('cookiecutters_dir', '~/.cookiecutters')
172
173
except ConfigDoesNotExistException:
174
print("Configuration file not found, using defaults")
175
config = get_user_config(default_config=True)
176
```
177
178
### Environment-Specific Configuration
179
180
```python
181
import os
182
from cookiecutter.config import get_user_config
183
184
# Use different config for different environments
185
if os.environ.get('ENVIRONMENT') == 'development':
186
config = get_user_config(config_file='~/.cookiecutter-dev.yaml')
187
elif os.environ.get('ENVIRONMENT') == 'production':
188
config = get_user_config(config_file='~/.cookiecutter-prod.yaml')
189
else:
190
config = get_user_config() # Default config
191
192
# Override with environment variables
193
if 'COOKIECUTTER_AUTHOR' in os.environ:
194
if 'default_context' not in config:
195
config['default_context'] = {}
196
config['default_context']['full_name'] = os.environ['COOKIECUTTER_AUTHOR']
197
```