0
# Utilities
1

2
AWS integration helpers, framework detection, file operations, and various utility functions for S3 operations, environment management, and deployment assistance. These utilities support Zappa's core functionality and provide convenience functions for common operations.
3

4
## Capabilities
5

6
### Framework Auto-Detection
7

8
Automatically detect and configure popular Python web frameworks.
9

10
```python { .api }
11
def detect_django_settings():
12
    """
13
    Auto-detect Django settings module path.
14
    
15
    Searches for Django settings in common locations and patterns
16
    to automatically configure Django applications for deployment.
17
    
18
    Returns:
19
    str or None: Django settings module path if found
20
    """
21
```
22

23
```python { .api }
24
def detect_flask_apps():
25
    """
26
    Auto-detect Flask application instances in code.
27
    
28
    Scans Python files for Flask app instances to automatically
29
    configure Flask applications for serverless deployment.
30
    
31
    Returns:
32
    list: List of detected Flask app paths
33
    """
34
```
35

36
### AWS/S3 Integration
37

38
Utilities for working with AWS services and S3 operations.
39

40
```python { .api }
41
def parse_s3_url(url):
42
    """
43
    Parse S3 URLs into bucket and key components.
44
    
45
    Extracts bucket name and object key from various S3 URL formats
46
    including s3://, https://, and virtual-hosted-style URLs.
47
    
48
    Parameters:
49
    - url: str, S3 URL to parse
50
    
51
    Returns:
52
    tuple: (bucket_name, key) or (None, None) if invalid
53
    """
54
```
55

56
```python { .api }
57
def is_valid_bucket_name(bucket):
58
    """
59
    Validate S3 bucket name format compliance.
60
    
61
    Checks bucket name against S3 naming rules including length,
62
    character restrictions, and DNS compliance.
63
    
64
    Parameters:
65
    - bucket: str, bucket name to validate
66
    
67
    Returns:
68
    bool: True if bucket name is valid
69
    """
70
```
71

72
```python { .api }
73
def merge_headers(event):
74
    """
75
    Merge HTTP headers from Lambda event data.
76
    
77
    Combines headers from API Gateway event, handling case-insensitive
78
    merging and multi-valued headers properly.
79
    
80
    Parameters:
81
    - event: dict, API Gateway Lambda proxy event
82
    
83
    Returns:
84
    dict: Merged headers dictionary
85
    """
86
```
87

88
### Environment Management
89

90
Utilities for managing Python environments and runtime detection.
91

92
```python { .api }
93
def get_venv_from_python_version(python_version=None):
94
    """
95
    Get virtual environment path for Python version.
96
    
97
    Determines appropriate virtual environment path based on
98
    Python version and system configuration.
99
    
100
    Parameters:
101
    - python_version: str, Python version string (optional)
102
    
103
    Returns:
104
    str: Path to virtual environment
105
    """
106
```
107

108
```python { .api }
109
def get_runtime_from_python_version(python_version=None):
110
    """
111
    Map Python version to AWS Lambda runtime identifier.
112
    
113
    Converts Python version string to corresponding Lambda
114
    runtime identifier for function configuration.
115
    
116
    Parameters:  
117
    - python_version: str, Python version string (optional)
118
    
119
    Returns:
120
    str: Lambda runtime identifier (e.g., 'python3.9')
121
    """
122
```
123

124
### File System Operations
125

126
Enhanced file operations for deployment package management.
127

128
```python { .api }
129
def copytree(src, dst, symlinks=False, ignore=None, copy_function=None):
130
    """
131
    Enhanced directory copying with metadata preservation.
132
    
133
    Copies directory tree with support for symbolic links,
134
    ignore patterns, and custom copy functions.
135
    
136
    Parameters:
137
    - src: str, source directory path
138
    - dst: str, destination directory path  
139
    - symlinks: bool, copy symbolic links as links
140
    - ignore: callable, function to ignore files/directories
141
    - copy_function: callable, custom file copy function
142
    
143
    Returns:
144
    str: Destination directory path
145
    """
146
```
147

148
```python { .api }
149
def contains_python_files_or_subdirs(folder):
150
    """
151
    Check if directory contains Python files or subdirectories.
152
    
153
    Recursively scans directory to determine if it contains
154
    Python source files or subdirectories with Python code.
155
    
156
    Parameters:
157
    - folder: str, directory path to check
158
    
159
    Returns:
160
    bool: True if Python files or subdirs found
161
    """
162
```
163

164
```python { .api }
165
def conflicts_with_a_neighbouring_module(module_path):
166
    """
167
    Detect Python module naming conflicts.
168
    
169
    Checks if module name conflicts with neighboring modules
170
    that could cause import resolution issues.
171
    
172
    Parameters:
173
    - module_path: str, path to module to check
174
    
175
    Returns:
176
    bool: True if naming conflict detected
177
    """
178
```
179

180
### Event Source Management
181

182
Manage AWS event sources for Lambda functions.
183

184
```python { .api }
185
def add_event_source(event_source, function_name, **kwargs):
186
    """
187
    Add event source trigger to Lambda function.
188
    
189
    Configures event source (S3, DynamoDB, Kinesis, etc.) to
190
    trigger Lambda function execution.
191
    
192
    Parameters:
193
    - event_source: dict, event source configuration
194
    - function_name: str, Lambda function name
195
    - **kwargs: Additional configuration options
196
    
197
    Returns:
198
    dict: Event source mapping configuration
199
    """
200
```
201

202
```python { .api }
203
def remove_event_source(event_source, function_name):
204
    """
205
    Remove event source trigger from Lambda function.
206
    
207
    Removes configured event source mapping and stops
208
    triggering function from the event source.
209
    
210
    Parameters:
211
    - event_source: dict, event source configuration
212
    - function_name: str, Lambda function name
213
    
214
    Returns:
215
    bool: True if removal successful
216
    """
217
```
218

219
```python { .api }
220
def get_event_source_status(event_source, function_name):
221
    """
222
    Get current event source configuration status.
223
    
224
    Retrieves status and configuration of event source mapping
225
    for the specified Lambda function.
226
    
227
    Parameters:
228
    - event_source: dict, event source configuration  
229
    - function_name: str, Lambda function name
230
    
231
    Returns:
232
    dict: Event source status and configuration
233
    """
234
```
235

236
```python { .api }
237
def get_topic_name(lambda_name):
238
    """
239
    Generate SNS topic name for Lambda integration.
240
    
241
    Creates standardized SNS topic name for Lambda function
242
    based on function name and naming conventions.
243
    
244
    Parameters:
245
    - lambda_name: str, Lambda function name
246
    
247
    Returns:
248
    str: Generated SNS topic name
249
    """
250
```
251

252
### Data Processing Utilities
253

254
General-purpose data processing and formatting functions.
255

256
```python { .api }
257
def human_size(bytes_size):
258
    """
259
    Convert byte counts to human-readable format.
260
    
261
    Formats byte size with appropriate units (B, KB, MB, GB)
262
    for user-friendly display.
263
    
264
    Parameters:
265
    - bytes_size: int, size in bytes
266
    
267
    Returns:
268
    str: Human-readable size string (e.g., "1.5 MB")
269
    """
270
```
271

272
```python { .api }
273
def string_to_timestamp(time_string):
274
    """
275
    Convert time strings to Unix timestamps.
276
    
277
    Parses various time string formats and converts to
278
    Unix timestamp for consistent time handling.
279
    
280
    Parameters:
281
    - time_string: str, time string to convert
282
    
283
    Returns:
284
    float: Unix timestamp
285
    """
286
```
287

288
```python { .api }
289
def titlecase_keys(dictionary):
290
    """
291
    Convert dictionary keys to title case format.
292
    
293
    Transforms dictionary keys to title case for consistent
294
    formatting in HTTP headers and API responses.
295
    
296
    Parameters:
297
    - dictionary: dict, dictionary to transform
298
    
299
    Returns:
300
    dict: Dictionary with title-cased keys
301
    """
302
```
303

304
### Validation Functions
305

306
Validation utilities for names, data, and configurations.
307

308
```python { .api }
309
def validate_name(name):
310
    """
311
    Validate AWS resource name compliance.
312
    
313
    Checks resource name against AWS naming conventions
314
    and restrictions for Lambda functions and other resources.
315
    
316
    Parameters:
317
    - name: str, resource name to validate
318
    
319
    Returns:
320
    bool: True if name is valid
321
    """
322
```
323

324
```python { .api }
325
def validate_json_serializable(data):
326
    """
327
    Validate data structures for JSON serialization.
328
    
329
    Checks if data can be properly serialized to JSON,
330
    useful for Lambda payloads and API responses.
331
    
332
    Parameters:
333
    - data: any, data to validate
334
    
335
    Returns:
336
    bool: True if JSON serializable
337
    """
338
```
339

340
### Version Management
341

342
Check for updates and manage version information.
343

344
```python { .api }
345
def check_new_version_available():
346
    """
347
    Check PyPI for newer Zappa versions.
348
    
349
    Queries PyPI API to determine if a newer version of
350
    Zappa is available for upgrade.
351
    
352
    Returns:
353
    dict or None: Version information if update available
354
    """
355
```
356

357
### Logging Utilities
358

359
Specialized logging formatters and utilities.
360

361
```python { .api }
362
def ApacheNCSAFormatter():
363
    """
364
    Create Apache NCSA compatible log formatter.
365
    
366
    Returns logging formatter that produces Apache NCSA
367
    Common Log Format entries for web request logging.
368
    
369
    Returns:
370
    logging.Formatter: Configured log formatter
371
    """
372
```
373

374
## Constants
375

376
```python { .api }
377
# Default text MIME types for response handling
378
DEFAULT_TEXT_MIMETYPES = (
379
    'application/json',
380
    'application/javascript', 
381
    'application/xml',
382
    'application/vnd.api+json',
383
    'text/css',
384
    'text/html',
385
    'text/javascript',
386
    'text/plain',
387
    'text/xml'
388
)
389
```
390

391
## Usage Examples
392

393
### Framework Detection
394

395
```python
396
from zappa.utilities import detect_django_settings, detect_flask_apps
397

398
# Auto-detect Django settings
399
django_settings = detect_django_settings()
400
if django_settings:
401
    print(f"Found Django settings: {django_settings}")
402

403
# Auto-detect Flask apps
404
flask_apps = detect_flask_apps()
405
for app_path in flask_apps:
406
    print(f"Found Flask app: {app_path}")
407
```
408

409
### S3 URL Processing
410

411
```python
412
from zappa.utilities import parse_s3_url, is_valid_bucket_name
413

414
# Parse S3 URLs
415
bucket, key = parse_s3_url('s3://my-bucket/path/to/file.zip')
416
print(f"Bucket: {bucket}, Key: {key}")
417

418
# Validate bucket names
419
if is_valid_bucket_name('my-deployment-bucket'):
420
    print("Bucket name is valid")
421
```
422

423
### Environment Detection
424

425
```python
426
from zappa.utilities import get_runtime_from_python_version, get_venv_from_python_version
427

428
# Get Lambda runtime for Python version
429
runtime = get_runtime_from_python_version('3.9.7')
430
print(f"Lambda runtime: {runtime}")  # python3.9
431

432
# Get virtual environment path
433
venv_path = get_venv_from_python_version('3.9')
434
print(f"Virtual env: {venv_path}")
435
```
436

437
### File Operations
438

439
```python
440
from zappa.utilities import copytree, contains_python_files_or_subdirs
441

442
# Copy directory with exclusions
443
def ignore_patterns(dir, files):
444
    return [f for f in files if f.endswith('.pyc')]
445

446
copytree('src/', 'dist/', ignore=ignore_patterns)
447

448
# Check for Python content
449
if contains_python_files_or_subdirs('my_package/'):
450
    print("Directory contains Python code")
451
```
452

453
### Data Formatting
454

455
```python
456
from zappa.utilities import human_size, string_to_timestamp
457

458
# Format file sizes
459
size = human_size(1536000)  # "1.5 MB"
460
print(f"Package size: {size}")
461

462
# Convert timestamps
463
timestamp = string_to_timestamp('2023-01-01T12:00:00Z')
464
print(f"Timestamp: {timestamp}")
465
```
466

467
### Event Source Management
468

469
```python
470
from zappa.utilities import add_event_source, get_topic_name
471

472
# Configure S3 event source
473
event_source = {
474
    'Events': ['s3:ObjectCreated:*'],
475
    'Bucket': 'my-uploads-bucket',
476
    'Filter': {'Key': {'FilterRules': [{'Name': 'prefix', 'Value': 'uploads/'}]}}
477
}
478

479
add_event_source(event_source, 'my-processor-function')
480

481
# Generate SNS topic name
482
topic_name = get_topic_name('my-function')
483
print(f"SNS topic: {topic_name}")
484
```