=========
apig-wsgi
=========
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/apig-wsgi/main.yml?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/apig-wsgi/actions?workflow=CI
.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
:target: https://github.com/adamchainz/apig-wsgi/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/apig-wsgi.svg?style=for-the-badge
:target: https://pypi.org/project/apig-wsgi/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
Wrap a `WSGI <https://peps.python.org/pep-3333/>`__ application in an AWS Lambda handler function for running on API Gateway or an ALB.
A quick example:
.. code-block:: python
from apig_wsgi import make_lambda_handler
from myapp.wsgi import app
# Configure this as your entry point in AWS Lambda
lambda_handler = make_lambda_handler(app)
Installation
============
Use **pip**:
.. code-block:: sh
python -m pip install apig-wsgi
Python 3.8 to 3.12 supported.
----
**Working on a Django project?**
Improve your skills with `one of my books <https://adamj.eu/books/>`__.
----
Usage
=====
Use apig-wsgi in your AWS Lambda Function that you attach to one of:
* A `Lambda Function URL <https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html>`__
* An `API Gateway “HTTP API” <https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html>`__
* An `API Gateway “REST API” <https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html>`__
* An `ALB <https://docs.aws.amazon.com/lambda/latest/dg/services-alb.html>`__
Both “format version 1” and “format version 2” are supported
(`documentation <https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html>`__).
apig-wsgi will automatically detect the version in use.
At time of writing, “format version 2” is used for Lambda Function URL’s and API Gateway HTTP API’s.
``make_lambda_handler(app, binary_support=None, non_binary_content_type_prefixes=None)``
----------------------------------------------------------------------------------------
``app`` should be a WSGI app, for example from Django's ``wsgi.py`` or Flask's
``Flask()`` object.
``binary_support`` configures whether responses containing binary are
supported. The default, ``None``, means to automatically detect this from the
format version of the event - on it defaults to ``True`` for format version 2,
and ``False`` for format version 1. Depending on how you're deploying your
lambda function, you may need extra configuration before you can enable binary
responses:
* ALB’s support binary responses by default.
* API Gateway HTTP API’s support binary responses by default (and default to
event format version 2).
* API Gateway REST API’s (the “old” style) require you to add ``'*/*'`` in the
“binary media types” configuration. You will need to configure this through
API Gateway directly, CloudFormation, SAM, or whatever tool your project is
using. Whilst this supports a list of binary media types, using ``'*/*'`` is
the best way to configure it, since it is used to match the request 'Accept'
header as well, which WSGI applications often ignore. You may need to delete
and recreate your stages for this value to be copied over.
Note that binary responses aren't sent if your response has a 'Content-Type'
starting 'text/', 'application/json' or 'application/vnd.api+json' - this
is to support sending larger text responses, since the base64 encoding would
otherwise inflate the content length. To avoid base64 encoding other content
types, you can set ``non_binary_content_type_prefixes`` to a list or tuple of
content type prefixes of your choice (which replaces the default list).
If the event from API Gateway contains the ``requestContext`` key, for example
on format version 2 or from custom request authorizers, this will be available
in the WSGI environ at the key ``apig_wsgi.request_context``.
If you want to inspect the full event from API Gateway, it's available in the
WSGI environ at the key ``apig_wsgi.full_event``.
If you need the
`Lambda Context object <https://docs.aws.amazon.com/lambda/latest/dg/python-context.html>`__,
it's available in the WSGI environ at the key ``apig_wsgi.context``.
If you’re using “format version 1”, multiple values for request and response
headers and query parameters are supported. They are enabled automatically on
API Gateway but need `explict activation on
ALB’s <https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html#multi-value-headers>`__.
If you need to determine from within your application if multiple header values
are enabled, you can can check the ``apgi_wsgi.multi_value_headers`` key in the
WSGI environ, which is ``True`` if they are enabled and ``False`` otherwise.
Example
=======
An example Django project with Ansible deployment is provided in the ``example/`` directory in the repository.
See the ``README.rst`` there for guidance.
Raw data
{
"_id": null,
"home_page": "https://github.com/adamchainz/apig-wsgi",
"name": "apig-wsgi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "AWS,Lambda,API Gateway,APIG",
"author": "Adam Johnson",
"author_email": "me@adamj.eu",
"download_url": "https://files.pythonhosted.org/packages/7d/9c/76a3300e25efe32d07331274cab1c504771202026d0c852614383cd46bd7/apig_wsgi-2.18.0.tar.gz",
"platform": null,
"description": "=========\napig-wsgi\n=========\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/apig-wsgi/main.yml?branch=main&style=for-the-badge\n :target: https://github.com/adamchainz/apig-wsgi/actions?workflow=CI\n\n.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge\n :target: https://github.com/adamchainz/apig-wsgi/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/apig-wsgi.svg?style=for-the-badge\n :target: https://pypi.org/project/apig-wsgi/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\nWrap a `WSGI <https://peps.python.org/pep-3333/>`__ application in an AWS Lambda handler function for running on API Gateway or an ALB.\n\nA quick example:\n\n.. code-block:: python\n\n from apig_wsgi import make_lambda_handler\n from myapp.wsgi import app\n\n # Configure this as your entry point in AWS Lambda\n lambda_handler = make_lambda_handler(app)\n\n\nInstallation\n============\n\nUse **pip**:\n\n.. code-block:: sh\n\n python -m pip install apig-wsgi\n\nPython 3.8 to 3.12 supported.\n\n----\n\n**Working on a Django project?**\nImprove your skills with `one of my books <https://adamj.eu/books/>`__.\n\n----\n\nUsage\n=====\n\nUse apig-wsgi in your AWS Lambda Function that you attach to one of:\n\n* A `Lambda Function URL <https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html>`__\n* An `API Gateway \u201cHTTP API\u201d <https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html>`__\n* An `API Gateway \u201cREST API\u201d <https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html>`__\n* An `ALB <https://docs.aws.amazon.com/lambda/latest/dg/services-alb.html>`__\n\n\nBoth \u201cformat version 1\u201d and \u201cformat version 2\u201d are supported\n(`documentation <https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html>`__).\napig-wsgi will automatically detect the version in use.\nAt time of writing, \u201cformat version 2\u201d is used for Lambda Function URL\u2019s and API Gateway HTTP API\u2019s.\n\n``make_lambda_handler(app, binary_support=None, non_binary_content_type_prefixes=None)``\n----------------------------------------------------------------------------------------\n\n``app`` should be a WSGI app, for example from Django's ``wsgi.py`` or Flask's\n``Flask()`` object.\n\n``binary_support`` configures whether responses containing binary are\nsupported. The default, ``None``, means to automatically detect this from the\nformat version of the event - on it defaults to ``True`` for format version 2,\nand ``False`` for format version 1. Depending on how you're deploying your\nlambda function, you may need extra configuration before you can enable binary\nresponses:\n\n* ALB\u2019s support binary responses by default.\n* API Gateway HTTP API\u2019s support binary responses by default (and default to\n event format version 2).\n* API Gateway REST API\u2019s (the \u201cold\u201d style) require you to add ``'*/*'`` in the\n \u201cbinary media types\u201d configuration. You will need to configure this through\n API Gateway directly, CloudFormation, SAM, or whatever tool your project is\n using. Whilst this supports a list of binary media types, using ``'*/*'`` is\n the best way to configure it, since it is used to match the request 'Accept'\n header as well, which WSGI applications often ignore. You may need to delete\n and recreate your stages for this value to be copied over.\n\nNote that binary responses aren't sent if your response has a 'Content-Type'\nstarting 'text/', 'application/json' or 'application/vnd.api+json' - this\nis to support sending larger text responses, since the base64 encoding would\notherwise inflate the content length. To avoid base64 encoding other content\ntypes, you can set ``non_binary_content_type_prefixes`` to a list or tuple of\ncontent type prefixes of your choice (which replaces the default list).\n\nIf the event from API Gateway contains the ``requestContext`` key, for example\non format version 2 or from custom request authorizers, this will be available\nin the WSGI environ at the key ``apig_wsgi.request_context``.\n\nIf you want to inspect the full event from API Gateway, it's available in the\nWSGI environ at the key ``apig_wsgi.full_event``.\n\nIf you need the\n`Lambda Context object <https://docs.aws.amazon.com/lambda/latest/dg/python-context.html>`__,\nit's available in the WSGI environ at the key ``apig_wsgi.context``.\n\nIf you\u2019re using \u201cformat version 1\u201d, multiple values for request and response\nheaders and query parameters are supported. They are enabled automatically on\nAPI Gateway but need `explict activation on\nALB\u2019s <https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html#multi-value-headers>`__.\nIf you need to determine from within your application if multiple header values\nare enabled, you can can check the ``apgi_wsgi.multi_value_headers`` key in the\nWSGI environ, which is ``True`` if they are enabled and ``False`` otherwise.\n\nExample\n=======\n\nAn example Django project with Ansible deployment is provided in the ``example/`` directory in the repository.\nSee the ``README.rst`` there for guidance.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Wrap a WSGI application in an AWS Lambda handler function for running on API Gateway or an ALB.",
"version": "2.18.0",
"project_urls": {
"Changelog": "https://github.com/adamchainz/apig-wsgi/blob/main/CHANGELOG.rst",
"Homepage": "https://github.com/adamchainz/apig-wsgi",
"Mastodon": "https://fosstodon.org/@adamchainz",
"Twitter": "https://twitter.com/adamchainz"
},
"split_keywords": [
"aws",
"lambda",
"api gateway",
"apig"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9883bea5c3b091481db0443da76dc32dac52aaa4d6d2b59fa52b6635f810bb32",
"md5": "ede50fafbfa51fd6f0a0ca5bc9bee1ba",
"sha256": "9132330bd1b1e9d1365cc1873e36b508930db65c5ed4d35f6234d332a6453fb9"
},
"downloads": -1,
"filename": "apig_wsgi-2.18.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ede50fafbfa51fd6f0a0ca5bc9bee1ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8359,
"upload_time": "2023-07-03T20:59:22",
"upload_time_iso_8601": "2023-07-03T20:59:22.168321Z",
"url": "https://files.pythonhosted.org/packages/98/83/bea5c3b091481db0443da76dc32dac52aaa4d6d2b59fa52b6635f810bb32/apig_wsgi-2.18.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7d9c76a3300e25efe32d07331274cab1c504771202026d0c852614383cd46bd7",
"md5": "a30482aeb3e1a98a966dac4e820ffe5d",
"sha256": "7e46eb15b32f644caeb8065ad494beae4f3114dc10009384db9191f2b16eceec"
},
"downloads": -1,
"filename": "apig_wsgi-2.18.0.tar.gz",
"has_sig": false,
"md5_digest": "a30482aeb3e1a98a966dac4e820ffe5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16976,
"upload_time": "2023-07-03T20:59:23",
"upload_time_iso_8601": "2023-07-03T20:59:23.885726Z",
"url": "https://files.pythonhosted.org/packages/7d/9c/76a3300e25efe32d07331274cab1c504771202026d0c852614383cd46bd7/apig_wsgi-2.18.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-03 20:59:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamchainz",
"github_project": "apig-wsgi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "apig-wsgi"
}
JSON
