0
# Package-Level Utilities
1

2
Core package functions and constants available at the top level for environment detection, version management, and system validation. These utilities provide essential functionality for Zappa's runtime environment compatibility checks.
3

4
## Capabilities
5

6
### Environment Detection
7

8
Detect execution environment and configure behavior accordingly.
9

10
```python { .api }
11
def running_in_docker() -> bool:
12
    """
13
    Determine if zappa is running in docker.
14
    
15
    Checks environment variables to determine if Zappa is executing
16
    within a Docker container, which affects Python version validation
17
    and allows usage of any Python version.
18
    
19
    Returns:
20
    bool: True if running in Docker environment
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
from zappa import running_in_docker
28

29
if running_in_docker():
30
    print("Running in Docker - relaxed version requirements")
31
else:
32
    print("Native execution - strict version validation")
33
```
34

35
## Version Management
36

37
### Version Information
38

39
Current package version and supported Python versions.
40

41
```python { .api }
42
__version__: str  # Current Zappa version (e.g., "0.60.2")
43

44
SUPPORTED_VERSIONS: list  # Supported Python versions
45
# [(3, 9), (3, 10), (3, 11), (3, 12), (3, 13)]
46

47
MINIMUM_SUPPORTED_MINOR_VERSION: int  # Minimum Python minor version (9)
48
```
49

50
**Usage Examples:**
51

52
```python
53
from zappa import __version__, SUPPORTED_VERSIONS, MINIMUM_SUPPORTED_MINOR_VERSION
54
import sys
55

56
# Check current Zappa version
57
print(f"Zappa version: {__version__}")
58

59
# Validate Python version compatibility
60
current_version = sys.version_info[:2]
61
if current_version in SUPPORTED_VERSIONS:
62
    print(f"Python {current_version[0]}.{current_version[1]} is supported")
63
else:
64
    supported = [f"{v[0]}.{v[1]}" for v in SUPPORTED_VERSIONS]
65
    print(f"Unsupported Python version. Supported: {supported}")
66

67
# Check minimum version requirement
68
if sys.version_info.minor >= MINIMUM_SUPPORTED_MINOR_VERSION:
69
    print("Meets minimum version requirement")
70
```
71

72
## Runtime Validation
73

74
The package automatically performs Python version validation on import with different behavior based on execution environment:
75

76
### Native Execution
77
- Enforces strict version compatibility against `SUPPORTED_VERSIONS`
78
- Raises `RuntimeError` for unsupported Python versions
79
- Ensures compatibility with AWS Lambda runtime requirements
80

81
### Docker Execution  
82
- Relaxed version requirements when `ZAPPA_RUNNING_IN_DOCKER=true`
83
- Only enforces minimum version requirement
84
- Allows flexibility for containerized deployments
85

86
**Environment Configuration:**
87

88
```bash
89
# Enable Docker mode (relaxed version checking)
90
export ZAPPA_RUNNING_IN_DOCKER=true
91

92
# Docker mode accepts various truthy values
93
export ZAPPA_RUNNING_IN_DOCKER=yes
94
export ZAPPA_RUNNING_IN_DOCKER=1
95
export ZAPPA_RUNNING_IN_DOCKER=True
96
```
97

98
## Constants Reference
99

100
```python { .api }
101
# Package version
102
__version__ = "0.60.2"
103

104
# Supported Python versions for AWS Lambda
105
SUPPORTED_VERSIONS = [
106
    (3, 9),   # Python 3.9
107
    (3, 10),  # Python 3.10  
108
    (3, 11),  # Python 3.11
109
    (3, 12),  # Python 3.12
110
    (3, 13)   # Python 3.13
111
]
112

113
# Minimum supported minor version
114
MINIMUM_SUPPORTED_MINOR_VERSION = 9
115
```
116

117
## Error Handling
118

119
The package performs automatic validation and raises descriptive errors:
120

121
```python
122
# Example error message for unsupported version
123
RuntimeError: This version of Python (3.8) is not supported!
124
Zappa (and AWS Lambda) support the following versions of Python: ['3.9', '3.10', '3.11', '3.12', '3.13']
125

126
# Example error for Docker mode with insufficient version
127
RuntimeError: This version of Python (3.8) is not supported!
128
Zappa requires a minimum version of 3.9
129
```
130

131
## Integration Examples
132

133
### Version-Aware Deployment
134

135
```python
136
from zappa import __version__, SUPPORTED_VERSIONS
137
from zappa.utilities import get_runtime_from_python_version
138
import sys
139

140
def check_deployment_compatibility():
141
    """Check if current environment is compatible for deployment."""
142
    current_version = sys.version_info[:2]
143
    
144
    if current_version not in SUPPORTED_VERSIONS:
145
        raise ValueError(f"Python {current_version[0]}.{current_version[1]} not supported for deployment")
146
    
147
    runtime = get_runtime_from_python_version()
148
    print(f"Using Zappa {__version__} with runtime {runtime}")
149
    return runtime
150
```
151

152
### Docker Integration
153

154
```python
155
from zappa import running_in_docker
156
import os
157

158
def configure_deployment_environment():
159
    """Configure deployment based on execution environment."""
160
    if running_in_docker():
161
        # Docker-specific configuration
162
        print("Configuring for Docker deployment")
163
        os.environ.setdefault('ZAPPA_DOCKER_BUILD', 'true')
164
        return 'docker'
165
    else:
166
        # Native environment configuration  
167
        print("Configuring for native deployment")
168
        return 'native'
169
```
170

171
### CI/CD Pipeline Integration
172

173
```bash
174
#!/bin/bash
175
# CI/CD script with Docker support
176

177
if [[ "$USE_DOCKER" == "true" ]]; then
178
    export ZAPPA_RUNNING_IN_DOCKER=true
179
    docker run --rm -v $(pwd):/app -w /app python:3.11 \
180
        pip install zappa && zappa deploy
181
else
182
    # Native deployment
183
    zappa deploy
184
fi
185
```