<p align="center">
<img src="https://logandk.github.io/serverless-wsgi/assets/header.svg">
</p>
[](https://nodei.co/npm/serverless-wsgi/)
[](http://www.serverless.com)
[](https://travis-ci.org/logandk/serverless-wsgi)
[](https://codecov.io/gh/logandk/serverless-wsgi)
[](https://david-dm.org/logandk/serverless-wsgi)
[](https://david-dm.org/logandk/serverless-wsgi?type=dev)
A Serverless Framework plugin to build your deploy Python WSGI applications using Serverless. Compatible
WSGI application frameworks include Flask, Django and Pyramid - for a complete list, see:
http://wsgi.readthedocs.io/en/latest/frameworks.html.
### Features
- Transparently converts API Gateway and ALB requests to and from standard WSGI requests
- Supports anything you'd expect from WSGI such as redirects, cookies, file uploads etc.
- Automatically downloads Python packages that you specify in `requirements.txt` and deploys them along with your application
- Convenient `wsgi serve` command for serving your application locally during development
- Includes CLI commands for remote execution of Python code (`wsgi exec`), shell commands (`wsgi command`), Flask CLI commands (`wsgi flask`) and Django management commands (`wsgi manage`)
- Supports both APIGatewayV1 and APIGatewayV2 payloads
## Install
```
sls plugin install -n serverless-wsgi
```
This will automatically add the plugin to `package.json` and the plugins section of `serverless.yml`.
## Flask configuration example
<p align="center">
<img src="https://logandk.github.io/serverless-wsgi/assets/hello-world.svg">
</p>
This example assumes that you have intialized your application as `app` inside `api.py`.
```
project
├── api.py
├── requirements.txt
└── serverless.yml
```
### api.py
A regular Flask application.
```python
from flask import Flask
app = Flask(__name__)
@app.route("/cats")
def cats():
return "Cats"
@app.route("/dogs/<id>")
def dog(id):
return "Dog"
```
### serverless.yml
Load the plugin and set the `custom.wsgi.app` configuration in `serverless.yml` to the
module path of your Flask application.
All functions that will use WSGI need to have `wsgi_handler.handler` set as the Lambda handler and
use the default `lambda-proxy` integration for API Gateway. This configuration example treats
API Gateway as a transparent proxy, passing all requests directly to your Flask application,
and letting the application handle errors, 404s etc.
_Note: The WSGI handler was called `wsgi.handler` earlier, but was renamed to `wsgi_handler.handler`
in `1.7.0`. The old name is still supported but using it will cause a deprecation warning._
```yaml
service: example
provider:
name: aws
runtime: python3.6
plugins:
- serverless-wsgi
functions:
api:
handler: wsgi_handler.handler
events:
- http: ANY /
- http: ANY /{proxy+}
custom:
wsgi:
app: api.app
```
### requirements.txt
Add Flask to the application bundle.
```
Flask==1.0.2
```
## Deployment
Simply run the serverless deploy command as usual:
```
$ sls deploy
Serverless: Using Python specified in "runtime": python3.6
Serverless: Packaging Python WSGI handler...
Serverless: Packaging required Python packages...
Serverless: Linking required Python packages...
Serverless: Packaging service...
Serverless: Excluding development dependencies...
Serverless: Unlinking required Python packages...
Serverless: Uploading CloudFormation file to S3...
Serverless: Uploading artifacts...
Serverless: Uploading service .zip file to S3 (864.57 KB)...
Serverless: Validating template...
Serverless: Updating Stack...
Serverless: Checking Stack update progress...
..............
Serverless: Stack update finished...
```
## Other frameworks
Set `custom.wsgi.app` in `serverless.yml` according to your WSGI callable:
- For Pyramid, use [make_wsgi_app](http://docs.pylonsproject.org/projects/pyramid/en/latest/api/config.html#pyramid.config.Configurator.make_wsgi_app) to intialize the callable
- Django is configured for WSGI by default, set the callable to `<project_name>.wsgi.application`. See https://docs.djangoproject.com/en/1.10/howto/deployment/wsgi/ for more information.
## Usage
### Automatic requirement packaging
You'll need to include any packages that your application uses in the bundle
that's deployed to AWS Lambda. This plugin helps you out by doing this automatically,
as long as you specify your required packages in a `requirements.txt` file in the root
of your Serverless service path:
```
Flask==1.0.2
requests==2.21.0
```
For more information, see https://pip.pypa.io/en/latest/user_guide/#requirements-files.
The `serverless-wsgi` plugin itself depends on `werkzeug` and will package it automatically,
even if `werkzeug` is not present in your `requirements.txt`.
You can use the requirement packaging functionality of _serverless-wsgi_ without the WSGI
handler itself by including the plugin in your `serverless.yml` configuration, without specifying
the `custom.wsgi.app` setting. This will omit the WSGI handler from the package, but include
any requirements specified in `requirements.txt`.
If you don't want to use automatic requirement packaging you can set `custom.wsgi.packRequirements` to false:
```yaml
custom:
wsgi:
app: api.app
packRequirements: false
```
In order to pass additional arguments to `pip` when installing requirements, the `pipArgs` configuration
option is available:
```yaml
custom:
wsgi:
app: api.app
pipArgs: --no-deps
```
For a more advanced approach to packaging requirements, consider using https://github.com/UnitedIncome/serverless-python-requirements.
When the `serverless-python-requirements` is added to `serverless.yml`, the `packRequirements` option
is set to `false` by default.
If you have `packRequirements` set to `false`, or if you use `serverless-python-requirements`, remember to add
`werkzeug` explicitly in your `requirements.txt`.
### Python version
Python is used for packaging requirements and serving the app when invoking `sls wsgi serve`. By
default, the current runtime setting is expected to be the name of the Python binary in `PATH`,
for instance `python3.6`. If this is not the name of your Python binary, override it using the
`pythonBin` option:
```yaml
custom:
wsgi:
app: api.app
pythonBin: python3
```
### Local server
<p align="center">
<img src="https://logandk.github.io/serverless-wsgi/assets/serve.svg">
</p>
For convenience, a `sls wsgi serve` command is provided to run your WSGI application
locally. This command requires the `werkzeug` Python package to be installed,
and acts as a simple wrapper for starting werkzeug's built-in HTTP server.
By default, the server will start on port 5000.
(Note: macOS [reserves port 5000](https://twitter.com/mitsuhiko/status/1462734023164416009)
for AirPlay by default, see below for instructions on changing the port.)
```
$ sls wsgi serve
* Running on http://localhost:5000/ (Press CTRL+C to quit)
* Restarting with stat
* Debugger is active!
```
Configure the port using the `-p` parameter:
```
$ sls wsgi serve -p 8000
* Running on http://localhost:8000/ (Press CTRL+C to quit)
* Restarting with stat
* Debugger is active!
```
When running locally, an environment variable named `IS_OFFLINE` will be set to `True`.
So, if you want to know when the application is running locally, check `os.environ["IS_OFFLINE"]`.
### Remote command execution
<p align="center">
<img src="https://logandk.github.io/serverless-wsgi/assets/command.svg">
</p>
The `wsgi exec` command lets you execute Python code remotely:
```
$ sls wsgi exec -c "import math; print((1 + math.sqrt(5)) / 2)"
1.618033988749895
$ cat count.py
for i in range(3):
print(i)
$ sls wsgi exec -f count.py
0
1
2
```
The `wsgi command` command lets you execute shell commands remotely:
```
$ sls wsgi command -c "pwd"
/var/task
$ cat script.sh
#!/bin/bash
echo "dlrow olleh" | rev
$ sls wsgi command -f script.sh
hello world
```
The `wsgi flask` command lets you execute [Flask CLI custom commands](http://flask.pocoo.org/docs/latest/cli/#custom-commands) remotely:
```
$ sls wsgi flask -c "my command"
Hello world!
```
The `wsgi manage` command lets you execute Django management commands remotely:
```
$ sls wsgi manage -c "check --list-tags"
admin
caches
database
models
staticfiles
templates
urls
```
All commands have `local` equivalents that let you run commands through `sls invoke local` rather
than `sls invoke`, i.e. on the local machine instead of through Lambda. The `local` commands (`sls wsgi command local`,
`sls wsgi exec local`, `sls wsgi flask local` and `sls wsgi manage local`) take the same arguments
as their remote counterparts documented above.
### Explicit routes
If you'd like to be explicit about which routes and HTTP methods should pass through to your
application, see the following example:
```yaml
service: example
provider:
name: aws
runtime: python3.6
plugins:
- serverless-wsgi
functions:
api:
handler: wsgi_handler.handler
events:
- http:
path: cats
method: get
integration: lambda-proxy
- http:
path: dogs/{id}
method: get
integration: lambda-proxy
custom:
wsgi:
app: api.app
```
### Custom domain names
If you use custom domain names with API Gateway, you might have a base path that is
at the beginning of your path, such as the stage (`/dev`, `/stage`, `/prod`). In this case, set
the `API_GATEWAY_BASE_PATH` environment variable to let `serverless-wsgi` know.
E.g, if you deploy your WSGI application to https://mydomain.com/api/myservice,
set `API_GATEWAY_BASE_PATH` to `api/myservice` (no `/` first).
The example below uses the [serverless-domain-manager](https://github.com/amplify-education/serverless-domain-manager)
plugin to handle custom domains in API Gateway:
```yaml
service: example
provider:
name: aws
runtime: python3.6
environment:
API_GATEWAY_BASE_PATH: ${self:custom.customDomain.basePath}
plugins:
- serverless-wsgi
- serverless-domain-manager
functions:
api:
handler: wsgi_handler.handler
events:
- http: ANY /
- http: ANY {proxy+}
custom:
wsgi:
app: api.app
customDomain:
basePath: ${opt:stage}
domainName: mydomain.name.com
stage: ${opt:stage}
createRoute53Record: true
```
**Note**: The **API_GATEWAY_BASE_PATH** configuration is only needed when using the payload V1. In the V2, the path does not have the **basePath** in the beginning.
### Using CloudFront
If you're configuring CloudFront manually in front of your API and setting
the Path in the CloudFront Origin to include your stage name, you'll need
to strip it out from the path supplied to WSGI. This is so that your app
doesn't generate URLs starting with `/production`.
Pass the `STRIP_STAGE_PATH=yes` environment variable to your application
to set this:
```yaml
service: example
provider:
name: aws
runtime: python3.6
environment:
STRIP_STAGE_PATH: yes
```
### File uploads
In order to accept file uploads from HTML forms, make sure to add `multipart/form-data` to
the list of content types with _Binary Support_ in your API Gateway API. The
[serverless-apigw-binary](https://github.com/maciejtreder/serverless-apigw-binary)
Serverless plugin can be used to automate this process.
Keep in mind that, when building Serverless applications, uploading
[directly to S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingHTTPPOST.html)
from the browser is usually the preferred approach.
### Raw context and event
The raw context and event from AWS Lambda are both accessible through the WSGI
request. The following example shows how to access them when using Flask:
```python
from flask import Flask, request
app = Flask(__name__)
@app.route("/")
def index():
print(request.environ['serverless.context'])
print(request.environ['serverless.event'])
```
For more information on these objects, read the documentation on [events](https://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html)
and the [invocation context](https://docs.aws.amazon.com/lambda/latest/dg/python-context.html).
### Text MIME types
By default, all MIME types starting with `text/` and the following whitelist are sent
through API Gateway in plain text. All other MIME types will have their response body
base64 encoded (and the `isBase64Encoded` API Gateway flag set) in order to be
delivered by API Gateway as binary data (remember to add any binary MIME types that
you're using to the _Binary Support_ list in API Gateway).
This is the default whitelist of plain text MIME types:
- `application/json`
- `application/javascript`
- `application/xml`
- `application/vnd.api+json`
- `image/svg+xml`
In order to add additional plain text MIME types to this whitelist, use the
`textMimeTypes` configuration option:
```yaml
custom:
wsgi:
app: api.app
textMimeTypes:
- application/custom+json
- application/vnd.company+json
```
### Preventing cold starts
Common ways to keep lambda functions warm include [scheduled events](https://serverless.com/framework/docs/providers/aws/events/schedule/)
and the [WarmUP plugin](https://github.com/FidelLimited/serverless-plugin-warmup). Both these event sources
are supported by default and will be ignored by `serverless-wsgi`.
### Alternative directory structure
If you have several functions in `serverless.yml` and want to organize them in
directories, e.g.:
```
project
├── web
│ ├── api.py
│ └── requirements.txt
├── serverless.yml
└── another_function.py
```
In this case, tell `serverless-wsgi` where to find the handler by prepending the
directory:
```yaml
service: example
provider:
name: aws
runtime: python3.6
plugins:
- serverless-wsgi
functions:
api:
handler: wsgi_handler.handler
events:
- http: ANY /
- http: ANY {proxy+}
another_function:
handler: another_function.handler
custom:
wsgi:
app: web/api.app
```
Requirements will now be installed into `web/`, rather than at in the service root directory.
The same rule applies when using the `individually: true` flag in the `package` settings, together
with the `module` option provided by `serverless-python-requirements`. In that case, both the requirements
and the WSGI handler will be installed into `web/`, if the function is configured with `module: "web"`.
## Usage without Serverless
The AWS API Gateway to WSGI mapping module is available on PyPI in the
`serverless-wsgi` package.
Use this package if you need to deploy Python Lambda functions to handle
API Gateway events directly, without using the Serverless framework.
```
pip install serverless-wsgi
```
Initialize your WSGI application and in your Lambda event handler, call
the request mapper:
```python
import app # Replace with your actual application
import serverless_wsgi
# If you need to send additional content types as text, add then directly
# to the whitelist:
#
# serverless_wsgi.TEXT_MIME_TYPES.append("application/custom+json")
def handler(event, context):
return serverless_wsgi.handle_request(app.app, event, context)
```
# Thanks
Thanks to [Zappa](https://github.com/Miserlou/Zappa), which has been both the
inspiration and source of several implementations that went into this project.
Thanks to [chalice](https://github.com/awslabs/chalice) for the
requirement packaging implementation.
Raw data
{
"_id": null,
"home_page": "https://github.com/logandk/serverless-wsgi",
"name": "serverless-wsgi",
"maintainer": "",
"docs_url": null,
"requires_python": ">3.6",
"maintainer_email": "",
"keywords": "wsgi serverless aws lambda api gateway apigw flask django pyramid",
"author": "Logan Raarup",
"author_email": "logan@logan.dk",
"download_url": "https://files.pythonhosted.org/packages/11/a6/9e84dc6c6557bdc4347973cba63a2bbacf6e4da46a8018ed0788f7a7a8e5/serverless-wsgi-3.0.3.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://logandk.github.io/serverless-wsgi/assets/header.svg\">\n</p>\n\n[](https://nodei.co/npm/serverless-wsgi/)\n\n[](http://www.serverless.com)\n[](https://travis-ci.org/logandk/serverless-wsgi)\n[](https://codecov.io/gh/logandk/serverless-wsgi)\n[](https://david-dm.org/logandk/serverless-wsgi)\n[](https://david-dm.org/logandk/serverless-wsgi?type=dev)\n\nA Serverless Framework plugin to build your deploy Python WSGI applications using Serverless. Compatible\nWSGI application frameworks include Flask, Django and Pyramid - for a complete list, see:\nhttp://wsgi.readthedocs.io/en/latest/frameworks.html.\n\n### Features\n\n- Transparently converts API Gateway and ALB requests to and from standard WSGI requests\n- Supports anything you'd expect from WSGI such as redirects, cookies, file uploads etc.\n- Automatically downloads Python packages that you specify in `requirements.txt` and deploys them along with your application\n- Convenient `wsgi serve` command for serving your application locally during development\n- Includes CLI commands for remote execution of Python code (`wsgi exec`), shell commands (`wsgi command`), Flask CLI commands (`wsgi flask`) and Django management commands (`wsgi manage`)\n- Supports both APIGatewayV1 and APIGatewayV2 payloads\n\n## Install\n\n```\nsls plugin install -n serverless-wsgi\n```\n\nThis will automatically add the plugin to `package.json` and the plugins section of `serverless.yml`.\n\n## Flask configuration example\n\n<p align=\"center\">\n <img src=\"https://logandk.github.io/serverless-wsgi/assets/hello-world.svg\">\n</p>\n\nThis example assumes that you have intialized your application as `app` inside `api.py`.\n\n```\nproject\n\u251c\u2500\u2500 api.py\n\u251c\u2500\u2500 requirements.txt\n\u2514\u2500\u2500 serverless.yml\n```\n\n### api.py\n\nA regular Flask application.\n\n```python\nfrom flask import Flask\napp = Flask(__name__)\n\n\n@app.route(\"/cats\")\ndef cats():\n return \"Cats\"\n\n\n@app.route(\"/dogs/<id>\")\ndef dog(id):\n return \"Dog\"\n```\n\n### serverless.yml\n\nLoad the plugin and set the `custom.wsgi.app` configuration in `serverless.yml` to the\nmodule path of your Flask application.\n\nAll functions that will use WSGI need to have `wsgi_handler.handler` set as the Lambda handler and\nuse the default `lambda-proxy` integration for API Gateway. This configuration example treats\nAPI Gateway as a transparent proxy, passing all requests directly to your Flask application,\nand letting the application handle errors, 404s etc.\n\n_Note: The WSGI handler was called `wsgi.handler` earlier, but was renamed to `wsgi_handler.handler`\nin `1.7.0`. The old name is still supported but using it will cause a deprecation warning._\n\n```yaml\nservice: example\n\nprovider:\n name: aws\n runtime: python3.6\n\nplugins:\n - serverless-wsgi\n\nfunctions:\n api:\n handler: wsgi_handler.handler\n events:\n - http: ANY /\n - http: ANY /{proxy+}\n\ncustom:\n wsgi:\n app: api.app\n```\n\n### requirements.txt\n\nAdd Flask to the application bundle.\n\n```\nFlask==1.0.2\n```\n\n## Deployment\n\nSimply run the serverless deploy command as usual:\n\n```\n$ sls deploy\nServerless: Using Python specified in \"runtime\": python3.6\nServerless: Packaging Python WSGI handler...\nServerless: Packaging required Python packages...\nServerless: Linking required Python packages...\nServerless: Packaging service...\nServerless: Excluding development dependencies...\nServerless: Unlinking required Python packages...\nServerless: Uploading CloudFormation file to S3...\nServerless: Uploading artifacts...\nServerless: Uploading service .zip file to S3 (864.57 KB)...\nServerless: Validating template...\nServerless: Updating Stack...\nServerless: Checking Stack update progress...\n..............\nServerless: Stack update finished...\n```\n\n## Other frameworks\n\nSet `custom.wsgi.app` in `serverless.yml` according to your WSGI callable:\n\n- For Pyramid, use [make_wsgi_app](http://docs.pylonsproject.org/projects/pyramid/en/latest/api/config.html#pyramid.config.Configurator.make_wsgi_app) to intialize the callable\n- Django is configured for WSGI by default, set the callable to `<project_name>.wsgi.application`. See https://docs.djangoproject.com/en/1.10/howto/deployment/wsgi/ for more information.\n\n## Usage\n\n### Automatic requirement packaging\n\nYou'll need to include any packages that your application uses in the bundle\nthat's deployed to AWS Lambda. This plugin helps you out by doing this automatically,\nas long as you specify your required packages in a `requirements.txt` file in the root\nof your Serverless service path:\n\n```\nFlask==1.0.2\nrequests==2.21.0\n```\n\nFor more information, see https://pip.pypa.io/en/latest/user_guide/#requirements-files.\n\nThe `serverless-wsgi` plugin itself depends on `werkzeug` and will package it automatically,\neven if `werkzeug` is not present in your `requirements.txt`.\n\nYou can use the requirement packaging functionality of _serverless-wsgi_ without the WSGI\nhandler itself by including the plugin in your `serverless.yml` configuration, without specifying\nthe `custom.wsgi.app` setting. This will omit the WSGI handler from the package, but include\nany requirements specified in `requirements.txt`.\n\nIf you don't want to use automatic requirement packaging you can set `custom.wsgi.packRequirements` to false:\n\n```yaml\ncustom:\n wsgi:\n app: api.app\n packRequirements: false\n```\n\nIn order to pass additional arguments to `pip` when installing requirements, the `pipArgs` configuration\noption is available:\n\n```yaml\ncustom:\n wsgi:\n app: api.app\n pipArgs: --no-deps\n```\n\nFor a more advanced approach to packaging requirements, consider using https://github.com/UnitedIncome/serverless-python-requirements.\nWhen the `serverless-python-requirements` is added to `serverless.yml`, the `packRequirements` option\nis set to `false` by default.\n\nIf you have `packRequirements` set to `false`, or if you use `serverless-python-requirements`, remember to add\n`werkzeug` explicitly in your `requirements.txt`.\n\n### Python version\n\nPython is used for packaging requirements and serving the app when invoking `sls wsgi serve`. By\ndefault, the current runtime setting is expected to be the name of the Python binary in `PATH`,\nfor instance `python3.6`. If this is not the name of your Python binary, override it using the\n`pythonBin` option:\n\n```yaml\ncustom:\n wsgi:\n app: api.app\n pythonBin: python3\n```\n\n### Local server\n\n<p align=\"center\">\n <img src=\"https://logandk.github.io/serverless-wsgi/assets/serve.svg\">\n</p>\n\nFor convenience, a `sls wsgi serve` command is provided to run your WSGI application\nlocally. This command requires the `werkzeug` Python package to be installed,\nand acts as a simple wrapper for starting werkzeug's built-in HTTP server.\n\nBy default, the server will start on port 5000.\n(Note: macOS [reserves port 5000](https://twitter.com/mitsuhiko/status/1462734023164416009)\nfor AirPlay by default, see below for instructions on changing the port.)\n\n```\n$ sls wsgi serve\n * Running on http://localhost:5000/ (Press CTRL+C to quit)\n * Restarting with stat\n * Debugger is active!\n```\n\nConfigure the port using the `-p` parameter:\n\n```\n$ sls wsgi serve -p 8000\n * Running on http://localhost:8000/ (Press CTRL+C to quit)\n * Restarting with stat\n * Debugger is active!\n```\n\nWhen running locally, an environment variable named `IS_OFFLINE` will be set to `True`.\nSo, if you want to know when the application is running locally, check `os.environ[\"IS_OFFLINE\"]`.\n\n### Remote command execution\n\n<p align=\"center\">\n <img src=\"https://logandk.github.io/serverless-wsgi/assets/command.svg\">\n</p>\n\nThe `wsgi exec` command lets you execute Python code remotely:\n\n```\n$ sls wsgi exec -c \"import math; print((1 + math.sqrt(5)) / 2)\"\n1.618033988749895\n\n$ cat count.py\nfor i in range(3):\n print(i)\n\n$ sls wsgi exec -f count.py\n0\n1\n2\n```\n\nThe `wsgi command` command lets you execute shell commands remotely:\n\n```\n$ sls wsgi command -c \"pwd\"\n/var/task\n\n$ cat script.sh\n#!/bin/bash\necho \"dlrow olleh\" | rev\n\n$ sls wsgi command -f script.sh\nhello world\n```\n\nThe `wsgi flask` command lets you execute [Flask CLI custom commands](http://flask.pocoo.org/docs/latest/cli/#custom-commands) remotely:\n\n```\n$ sls wsgi flask -c \"my command\"\nHello world!\n```\n\nThe `wsgi manage` command lets you execute Django management commands remotely:\n\n```\n$ sls wsgi manage -c \"check --list-tags\"\nadmin\ncaches\ndatabase\nmodels\nstaticfiles\ntemplates\nurls\n```\n\nAll commands have `local` equivalents that let you run commands through `sls invoke local` rather\nthan `sls invoke`, i.e. on the local machine instead of through Lambda. The `local` commands (`sls wsgi command local`,\n`sls wsgi exec local`, `sls wsgi flask local` and `sls wsgi manage local`) take the same arguments\nas their remote counterparts documented above.\n\n### Explicit routes\n\nIf you'd like to be explicit about which routes and HTTP methods should pass through to your\napplication, see the following example:\n\n```yaml\nservice: example\n\nprovider:\n name: aws\n runtime: python3.6\n\nplugins:\n - serverless-wsgi\n\nfunctions:\n api:\n handler: wsgi_handler.handler\n events:\n - http:\n path: cats\n method: get\n integration: lambda-proxy\n - http:\n path: dogs/{id}\n method: get\n integration: lambda-proxy\n\ncustom:\n wsgi:\n app: api.app\n```\n\n### Custom domain names\n\nIf you use custom domain names with API Gateway, you might have a base path that is\nat the beginning of your path, such as the stage (`/dev`, `/stage`, `/prod`). In this case, set\nthe `API_GATEWAY_BASE_PATH` environment variable to let `serverless-wsgi` know.\nE.g, if you deploy your WSGI application to https://mydomain.com/api/myservice,\nset `API_GATEWAY_BASE_PATH` to `api/myservice` (no `/` first).\n\nThe example below uses the [serverless-domain-manager](https://github.com/amplify-education/serverless-domain-manager)\nplugin to handle custom domains in API Gateway:\n\n```yaml\nservice: example\n\nprovider:\n name: aws\n runtime: python3.6\n environment:\n API_GATEWAY_BASE_PATH: ${self:custom.customDomain.basePath}\n\nplugins:\n - serverless-wsgi\n - serverless-domain-manager\n\nfunctions:\n api:\n handler: wsgi_handler.handler\n events:\n - http: ANY /\n - http: ANY {proxy+}\n\ncustom:\n wsgi:\n app: api.app\n customDomain:\n basePath: ${opt:stage}\n domainName: mydomain.name.com\n stage: ${opt:stage}\n createRoute53Record: true\n```\n\n**Note**: The **API_GATEWAY_BASE_PATH** configuration is only needed when using the payload V1. In the V2, the path does not have the **basePath** in the beginning.\n\n### Using CloudFront\n\nIf you're configuring CloudFront manually in front of your API and setting\nthe Path in the CloudFront Origin to include your stage name, you'll need\nto strip it out from the path supplied to WSGI. This is so that your app\ndoesn't generate URLs starting with `/production`.\n\nPass the `STRIP_STAGE_PATH=yes` environment variable to your application\nto set this:\n\n```yaml\nservice: example\n\nprovider:\n name: aws\n runtime: python3.6\n environment:\n STRIP_STAGE_PATH: yes\n```\n\n### File uploads\n\nIn order to accept file uploads from HTML forms, make sure to add `multipart/form-data` to\nthe list of content types with _Binary Support_ in your API Gateway API. The\n[serverless-apigw-binary](https://github.com/maciejtreder/serverless-apigw-binary)\nServerless plugin can be used to automate this process.\n\nKeep in mind that, when building Serverless applications, uploading\n[directly to S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingHTTPPOST.html)\nfrom the browser is usually the preferred approach.\n\n### Raw context and event\n\nThe raw context and event from AWS Lambda are both accessible through the WSGI\nrequest. The following example shows how to access them when using Flask:\n\n```python\nfrom flask import Flask, request\napp = Flask(__name__)\n\n\n@app.route(\"/\")\ndef index():\n print(request.environ['serverless.context'])\n print(request.environ['serverless.event'])\n```\n\nFor more information on these objects, read the documentation on [events](https://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html)\nand the [invocation context](https://docs.aws.amazon.com/lambda/latest/dg/python-context.html).\n\n### Text MIME types\n\nBy default, all MIME types starting with `text/` and the following whitelist are sent\nthrough API Gateway in plain text. All other MIME types will have their response body\nbase64 encoded (and the `isBase64Encoded` API Gateway flag set) in order to be\ndelivered by API Gateway as binary data (remember to add any binary MIME types that\nyou're using to the _Binary Support_ list in API Gateway).\n\nThis is the default whitelist of plain text MIME types:\n\n- `application/json`\n- `application/javascript`\n- `application/xml`\n- `application/vnd.api+json`\n- `image/svg+xml`\n\nIn order to add additional plain text MIME types to this whitelist, use the\n`textMimeTypes` configuration option:\n\n```yaml\ncustom:\n wsgi:\n app: api.app\n textMimeTypes:\n - application/custom+json\n - application/vnd.company+json\n```\n\n### Preventing cold starts\n\nCommon ways to keep lambda functions warm include [scheduled events](https://serverless.com/framework/docs/providers/aws/events/schedule/)\nand the [WarmUP plugin](https://github.com/FidelLimited/serverless-plugin-warmup). Both these event sources\nare supported by default and will be ignored by `serverless-wsgi`.\n\n### Alternative directory structure\n\nIf you have several functions in `serverless.yml` and want to organize them in\ndirectories, e.g.:\n\n```\nproject\n\u251c\u2500\u2500 web\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 api.py\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 requirements.txt\n\u251c\u2500\u2500 serverless.yml\n\u2514\u2500\u2500 another_function.py\n```\n\nIn this case, tell `serverless-wsgi` where to find the handler by prepending the\ndirectory:\n\n```yaml\nservice: example\n\nprovider:\n name: aws\n runtime: python3.6\n\nplugins:\n - serverless-wsgi\n\nfunctions:\n api:\n handler: wsgi_handler.handler\n events:\n - http: ANY /\n - http: ANY {proxy+}\n\n another_function:\n handler: another_function.handler\n\ncustom:\n wsgi:\n app: web/api.app\n```\n\nRequirements will now be installed into `web/`, rather than at in the service root directory.\n\nThe same rule applies when using the `individually: true` flag in the `package` settings, together\nwith the `module` option provided by `serverless-python-requirements`. In that case, both the requirements\nand the WSGI handler will be installed into `web/`, if the function is configured with `module: \"web\"`.\n\n## Usage without Serverless\n\nThe AWS API Gateway to WSGI mapping module is available on PyPI in the\n`serverless-wsgi` package.\n\nUse this package if you need to deploy Python Lambda functions to handle\nAPI Gateway events directly, without using the Serverless framework.\n\n```\npip install serverless-wsgi\n```\n\nInitialize your WSGI application and in your Lambda event handler, call\nthe request mapper:\n\n```python\nimport app # Replace with your actual application\nimport serverless_wsgi\n\n# If you need to send additional content types as text, add then directly\n# to the whitelist:\n#\n# serverless_wsgi.TEXT_MIME_TYPES.append(\"application/custom+json\")\n\ndef handler(event, context):\n return serverless_wsgi.handle_request(app.app, event, context)\n```\n\n# Thanks\n\nThanks to [Zappa](https://github.com/Miserlou/Zappa), which has been both the\ninspiration and source of several implementations that went into this project.\n\nThanks to [chalice](https://github.com/awslabs/chalice) for the\nrequirement packaging implementation.\n",
"bugtrack_url": null,
"license": "",
"summary": "Amazon AWS API Gateway WSGI wrapper",
"version": "3.0.3",
"project_urls": {
"Homepage": "https://github.com/logandk/serverless-wsgi"
},
"split_keywords": [
"wsgi",
"serverless",
"aws",
"lambda",
"api",
"gateway",
"apigw",
"flask",
"django",
"pyramid"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2f7cc41a9d692c94b8f4108d8b412f1567140127e4210c9df678e7c450356f59",
"md5": "60a5d5615b4458b4b527788f2f29837f",
"sha256": "6445fc00fb36654ab7546454da9d4ea450e1ff5ae144d1f99d8290ef96831dda"
},
"downloads": -1,
"filename": "serverless_wsgi-3.0.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "60a5d5615b4458b4b527788f2f29837f",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">3.6",
"size": 10797,
"upload_time": "2023-10-05T09:33:32",
"upload_time_iso_8601": "2023-10-05T09:33:32.752365Z",
"url": "https://files.pythonhosted.org/packages/2f/7c/c41a9d692c94b8f4108d8b412f1567140127e4210c9df678e7c450356f59/serverless_wsgi-3.0.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "11a69e84dc6c6557bdc4347973cba63a2bbacf6e4da46a8018ed0788f7a7a8e5",
"md5": "26b30151e940fdb02825aa09f52351b2",
"sha256": "5b526aa698d9d9332b53ff34d9f978b579f439f8abd530ceb2d183bb1a7d0820"
},
"downloads": -1,
"filename": "serverless-wsgi-3.0.3.tar.gz",
"has_sig": false,
"md5_digest": "26b30151e940fdb02825aa09f52351b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.6",
"size": 14601,
"upload_time": "2023-10-05T09:33:34",
"upload_time_iso_8601": "2023-10-05T09:33:34.588116Z",
"url": "https://files.pythonhosted.org/packages/11/a6/9e84dc6c6557bdc4347973cba63a2bbacf6e4da46a8018ed0788f7a7a8e5/serverless-wsgi-3.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-05 09:33:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "logandk",
"github_project": "serverless-wsgi",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "serverless-wsgi"
}
JSON
