0
# Zappa
1

2
Zappa is a comprehensive serverless deployment tool that enables developers to build and deploy event-driven Python applications (including WSGI web apps like Django and Flask) on AWS Lambda + API Gateway without any permanent infrastructure. It provides infinite scaling, zero downtime, and zero maintenance at a fraction of traditional hosting costs by leveraging AWS's serverless architecture where each request gets its own virtual HTTP server with a 40-millisecond lifecycle.
3

4
## Package Information
5

6
- **Package Name**: zappa  
7
- **Language**: Python
8
- **Installation**: `pip install zappa`
9

10
## Core Imports
11

12
```python
13
# Core deployment management
14
from zappa.core import Zappa
15

16
# Command line interface
17
from zappa.cli import ZappaCLI
18

19
# Lambda handler entry point
20
from zappa.handler import lambda_handler, LambdaHandler
21

22
# Async task decorators and execution
23
from zappa.asynchronous import task, task_sns, run, get_async_response
24

25
# WSGI utilities  
26
from zappa.wsgi import create_wsgi_request, ZappaWSGIMiddleware
27

28
# SSL certificate management
29
from zappa.letsencrypt import get_cert_and_update_domain
30

31
# Utility functions
32
from zappa.utilities import (
33
    detect_django_settings, 
34
    detect_flask_apps,
35
    parse_s3_url,
36
    human_size
37
)
38

39
# Package-level utilities
40
from zappa import running_in_docker, __version__
41
```
42

43
## Basic Usage
44

45
### CLI Deployment
46

47
```python
48
# Initialize a new Zappa project
49
from zappa.cli import ZappaCLI
50
cli = ZappaCLI()
51
cli.init()
52

53
# Deploy to AWS
54
cli.deploy()
55

56
# Update existing deployment  
57
cli.update()
58

59
# Check deployment status
60
cli.status()
61

62
# Remove deployment
63
cli.undeploy()
64
```
65

66
### Programmatic Deployment
67

68
```python
69
from zappa.core import Zappa
70

71
# Create Zappa instance
72
z = Zappa(
73
    boto_session=None,
74
    profile_name='default', 
75
    aws_region='us-east-1',
76
    load_credentials=True
77
)
78

79
# Create Lambda function
80
z.create_lambda_function(
81
    bucket='my-deployment-bucket',
82
    s3_key='my-app.zip',
83
    function_name='my-app',
84
    handler='app.lambda_handler'
85
)
86

87
# Deploy API Gateway
88
z.deploy_api_gateway(
89
    api_id='abc123',
90
    stage_name='prod'
91
)
92
```
93

94
## Architecture
95

96
Zappa's architecture consists of several key components:
97

98
- **Core Library**: The `Zappa` class provides deployment and AWS resource management
99
- **CLI Interface**: The `ZappaCLI` class handles command-line operations and user interaction
100
- **Lambda Handler**: Request processing and WSGI application execution in Lambda runtime
101
- **WSGI Support**: Middleware and utilities for converting Lambda events to WSGI requests
102
- **Async Processing**: Background task execution via Lambda or SNS
103
- **Utilities**: AWS integration helpers, framework detection, and file operations
104

105
This design enables seamless deployment of existing Python web applications to serverless infrastructure with minimal code changes.
106

107
## Capabilities
108

109
### Core Deployment Management
110

111
Primary AWS resource management including Lambda function creation, updates, configuration changes, API Gateway deployment, and rollback operations. These functions form the foundation of Zappa's serverless deployment capabilities.
112

113
```python { .api }
114
class Zappa:
115
    def create_lambda_function(self, **kwargs): ...
116
    def update_lambda_function(self, **kwargs): ...
117
    def update_lambda_configuration(self, **kwargs): ...
118
    def delete_lambda_function(self, function_name): ...
119
    def deploy_api_gateway(self, **kwargs): ...
120
    def undeploy_api_gateway(self, **kwargs): ...
121
```
122

123
[Core Deployment](./core-deployment.md)
124

125
### Command Line Interface
126

127
Complete CLI operations for deployment lifecycle management including project initialization, deployment, updates, status monitoring, log streaming, and cleanup operations.
128

129
```python { .api }
130
class ZappaCLI:
131
    def deploy(self): ...
132
    def update(self): ...
133
    def undeploy(self): ...
134
    def status(self): ...
135
    def tail(self): ...
136
    def rollback(self): ...
137
    def init(self): ...
138
    def shell(self): ...
139
```
140

141
[CLI Operations](./cli-operations.md)
142

143
### Lambda Request Processing
144

145
Lambda function handler and WSGI request processing for converting AWS Lambda events into standard HTTP requests that can be processed by web applications like Django and Flask.
146

147
```python { .api }
148
def lambda_handler(event, context): ...
149

150
class LambdaHandler:
151
    @classmethod 
152
    def lambda_handler(cls, event, context): ...
153
    def handler(self, event, context): ...
154
    def run_function(self, event, context): ...
155
```
156

157
[Request Processing](./request-processing.md)
158

159
### Asynchronous Task Execution
160

161
Background task processing using AWS Lambda and SNS for executing long-running operations asynchronously outside of HTTP request/response cycle.
162

163
```python { .api }
164
def task(func): ...
165
def task_sns(func): ...
166
def run(func, *args, **kwargs): ...
167
def get_async_response(response_id): ...
168

169
class LambdaAsyncResponse: ...
170
class SnsAsyncResponse: ...
171
```
172

173
[Async Tasks](./async-tasks.md)
174

175
### Utility Functions
176

177
AWS integration helpers, framework detection, file operations, and various utility functions for S3 operations, environment management, and deployment assistance.
178

179
```python { .api }
180
def detect_django_settings(): ...
181
def detect_flask_apps(): ...
182
def parse_s3_url(url): ...
183
def is_valid_bucket_name(bucket): ...
184
def get_runtime_from_python_version(version): ...
185
def human_size(bytes): ...
186
```
187

188
[Utilities](./utilities.md)
189

190
### SSL Certificate Management
191

192
Automated SSL certificate provisioning using Let's Encrypt ACME protocol for securing deployed applications with HTTPS.
193

194
```python { .api }
195
def get_cert_and_update_domain(**kwargs): ...
196
def get_cert(**kwargs): ...
197
def create_domain_key(): ...
198
def create_domain_csr(**kwargs): ...
199
def verify_challenge(**kwargs): ...
200
```
201

202
[SSL Management](./ssl-management.md)
203

204
### WSGI Request Processing
205

206
WSGI utilities for converting Lambda events to standard HTTP requests and middleware for AWS-specific processing requirements.
207

208
```python { .api }
209
def create_wsgi_request(event, script_name=None, base_path=None, trailing_slash=True): ...
210
def process_lambda_payload_v1(event): ...
211
def process_lambda_payload_v2(event): ...
212

213
class ZappaWSGIMiddleware:
214
    def __init__(self, application): ...
215
    def __call__(self, environ, start_response): ...
216
```
217

218
[WSGI Processing](./wsgi-processing.md)
219

220
### Package-Level Utilities
221

222
Core package functions and constants available at the top level for environment detection and version management.
223

224
```python { .api }
225
def running_in_docker() -> bool: ...
226

227
__version__: str
228
SUPPORTED_VERSIONS: list
229
MINIMUM_SUPPORTED_MINOR_VERSION: int
230
```
231

232
[Package Utilities](./package-utilities.md)
233

234
## Types
235

236
```python { .api }
237
# Core configuration types
238
class Zappa:
239
    def __init__(
240
        self,
241
        boto_session=None,
242
        profile_name=None,
243
        aws_region=None,
244
        load_credentials=True,
245
        desired_role_name=None,
246
        desired_role_arn=None,
247
        runtime="python3.13",
248
        tags=(),
249
        endpoint_urls={},
250
        xray_tracing=False,
251
        architecture=None
252
    ): ...
253

254
class ZappaCLI:
255
    def __init__(self): ...
256

257
# Handler types  
258
class LambdaHandler:
259
    def __init__(self): ...
260

261
# Async response types
262
class LambdaAsyncResponse:
263
    def __init__(self, **kwargs): ...
264

265
class SnsAsyncResponse(LambdaAsyncResponse):
266
    def __init__(self, **kwargs): ...
267

268
# Exception types
269
class AsyncException(Exception): ...
270
```