AWS SAM application template for Python 3.9

The purpose of this repository is to suggest a project folder structure and how to write functions that are easy to test. The approach used is TDD and SOLID principles following the best practices suggested by AWS.

IMPORTANT

The application uses Python 3.9 runtime (see template.yaml). Before go further be sure that the correct version of Python is installed and running. To check it

$ python3 -V
Python 3.9.6

If you are on macOS, you are using Homebrew and you have multiple version of Python installed on your system be sure to switch to the right version.

To check which versions are installed run

$ brew list | grep python
[email protected]
[email protected]

To switch

$ brew unlink [email protected]
$ brew unlink [email protected]
$ brew link --force [email protected]

Close and reopen the terminal or run rehash to make the switch effective.

The reference is this Stack Overflow post.

How to use it

The following steps assume you already installed and configured AWS SAM on your PC.

Init

1. create the SAM application using this repository as template

   $ sam init --location https://github.com/claranet-ch/aws-sam-application-template-python.git --name my-awesome-sam-app
   

2. create the virtual environment and install all dependencies for local development and testing

   $ ./create_venv.sh
   

3. activate the virtual environment

   $ source .venv/bin/activate
   

4. to check that everything is ready to use, run

   $ ./run_all_tests.sh
   

   the output should be like

   Running all tests ...
   
   .
   ----------------------------------------------------------------------
   Ran 1 test in 4.318s
   
   OK
   

Deploy

1. build the application

   $ sam build
   

2. deploy the application

   $ sam deploy --guided
   

Cleanup

Deletes an AWS SAM application by deleting the AWS CloudFormation stack, the artifacts that were packaged and deployed to Amazon S3 and Amazon ECR, and the AWS SAM template file.

$ sam delete

Implementation notes

Function handler

The logic of the lambda is isolated in one file with postfix _logic. The handler read the relevant data from the event and context objects, instantiates clients and pass all of them to the logic (see Dependency injection).

Layers

Layers are built by AWS SAM when you run sam build command.

IMPORTANT

Remember to add the content of requirements.txt located in each layer folder, in the requirements.txt file inside the folder tests/. This will allow to write and test your code locally.

Testing

The test runner is unittest build-in in Python standard library.

To write tests for AWS services we use botocore Stubber included in Boto3.

Logging

Instead of use the print() function, it is better to use the Python built-in logging library.

The code

import os
import logging
logger = logging.getLogger()
logger.setLevel(logging.INFO)

def lambda_handler(event, context):
   logger.info('## ENVIRONMENT VARIABLES')
   logger.info(os.environ)
   logger.info('## EVENT')
   logger.info(event)

See AWS Lambda function logging in Python.

Tracing

By default, the X-Ray tracing mode is enabled for all functions. Keeping in mind that

In Lambda, you can use the X-Ray SDK to extend the Invocation subsegment with additional subsegments for downstream calls, annotations, and metadata. You can't access the function segment directly or record work done outside of the handler invocation scope. See Using AWS Lambda with AWS X-Ray.

all functions must have a layer that contains the X-Ray SDK in order to record metadata and trace downstream calls.

The code to add

import boto3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

patch_all()

s3_client = boto3.client('s3')

def lambda_handler(event, context):
   ...

More resources

• License