AWS Lambda Templates - Python

Production-ready plug-and-play AWS Lambda templates in Python for different real-life scenarios.

The templates apply best practices by using AWS Lambda Powertools for:

CloudWatch Logs and Metrics
X-ray Tracing
Batch Processing
Event Handling
Parameter/Secret Loading

Templates

Bedrock Agent: Handle Bedrock Agent function-based actions
GraphQL API: Handle AppSync GraphQL requests
REST API: Handle REST API requests
DynamoDB Stream: Batch process stream events
EventBridge: Call external API on event
S3 to SQS: Send messages to queue on S3 object changes
SQS to DynamoDB: Batch Process SQS messages

Features

Templates come pre-wired with:

AWS Lambda Best Practices: Integrated AWS Lambda Powertools
Clean Architecture: Separation of concerns using the Repository pattern for data access
Data Modeling: Strong typing and validation using Pydantic
Infrastructure as Code: AWS CDK stacks
Testing: Comprehensive pytest suite with moto for AWS mocking and hypothesis for property-based testing
Code Quality: ruff for linting and formatting, pyright for type checking, and test coverage using coverage
Dependency Control: Poetry for dependency management and Dependabot for automated dependency updates
Documentation: Automatic documentation using MkDocs and mkdocstrings
Development environment: Dev Containers for dockerized development environment
Pre-commit Validations: pre-commit hooks
Workflow Automation: GitHub Actions for CI/CD and documentation auto-deployment to GitHub Pages

GitHub files

The repository also comes preloaded with these GitHub files:

AI Agent guidelines
Pull request template
Issue templates
- Bug report
- Feature request
- Question
Contributing guidelines
Funding file
Code owners
MIT License

How to use

Click this button to create a new repository for your project, then clone the new repository. Enjoy!

Rename the project

Run make project once after cloning, before any other setup steps:

make project NAME="my-project" DESCRIPTION="My project description" AUTHOR="Jane Doe" EMAIL="jane" GITHUB="janedoe"

Pass the following parameters:

Parameter	Description
`NAME`	Project new name
`DESCRIPTION`	Project short description
`AUTHOR`	Author name
`EMAIL`	Author email
`GITHUB`	GitHub username (for GitHub funding)
`SOURCE`	(optional) Source folder name

Prerequisites

Dev container

Docker

Local environment

Python 3.14+
Poetry
Docker (for Dev Containers)
AWS CDK CLI (for deployment)

Setup

Install dependencies

To install the project dependencies defined in pyproject.toml, run:

make install

Install pre-commit hooks

To install the pre-commit hooks for the project to format and lint your code automatically before committing, run:

make precommit

Activate virtual environment

To activate the virtual environment, run:

make venv

Format and lint code

To format and lint project code, run:

make lint

Run tests with coverage

To run all tests (including Hypothesis property-based tests) and show the coverage report, run:

make test

make test runs both standard pytest tests and Hypothesis property-based tests in a single command.

Deploy a stack

Infrastructure is defined as AWS CDK stacks under infra/stacks/. The CDK entry point is infra/app.py. The STACK environment variable selects which stack to synthesise.

make deploy STACK=<stack-key>

Pass AWS_PROFILE to use a named AWS CLI profile:

make deploy STACK=<stack-key> AWS_PROFILE=<my-profile>

Destroy a stack

make destroy STACK=<stack-key>

Generating documentation

To build and publish the project documentation to GitHub Pages, run:

make docs

That pushes the new documentation to the gh-pages branch. Make sure GitHub Pages is enabled in your repository settings and using the gh-pages branch for the documentation to be publicly available.

Local preview

To serve the documentation on a local server, run:

make local

Coding Conventions

camelCase for JSON: All models use alias_generator=to_camel so that JSON payloads use camelCase while Python attributes use snake_case.
Environment Variables: Managed via BaseSettings in settings.py files.
Documentation: Every field in a Pydantic model must include a Field(description="...").
Repository Pattern: All database calls are encapsulated in a Repository class for better testability.

Project Structure

├── .devcontainer                   # Dev container folder
│   ├── devcontainer.json           # Dev container configuration
│   └── Dockerfile                  # Dev container Dockerfile
├── .github                         # GitHub folder
│   ├── dependabot.yaml             # Dependabot configuration
│   ├── CODEOWNERS                  # Code owners
│   ├── FUNDING.yml                 # GitHub funding
│   ├── PULL_REQUEST_TEMPLATE.md    # Pull request template
│   ├── ISSUE_TEMPLATE              # Issue templates
│   │   ├── bug.md                  # Bug report template
│   │   ├── feature.md              # Feature request template
│   │   └── question.md             # Question template
│   └── workflows                   # GitHub Actions workflows
│       ├── check.yml               # Workflow to validate code on push
│       ├── deploy.yml              # Workflow to deploy infra and code
│       └── docs.yml                # Workflow to publish documentation
├── .gitignore                      # Git-ignored file list
├── .pre-commit-config.yaml         # Pre-commit configuration file
├── .vscode                         # VS Code folder
├── Makefile                        # Make commands
├── pyproject.toml                  # Configuration file for different tools
├── mkdocs.yml                      # MkDocs configuration file
├── docs                            # Documentation folder
│   ├── README.md                   # Read-me file & documentation home page
│   ├── CONTRIBUTING.md             # Contributing guidelines
│   ├── LICENSE.md                  # Project license
│   ├── template                    # Templates summary page
│   │   ├── agent.md                # Bedrock agent documentation page
│   │   ├── api.md                  # API documentation page
│   │   ├── eventbridge.md          # EventBridge documentation page
│   │   ├── graphql.md              # AppSync GRAPHQL documentation page
│   │   ├── s3.md                   # S3 documentation page
│   │   ├── stream.md               # Stream documentation page
│   │   └── sqs.md                  # S3 documentation page
│   └── reference                   # Reference section
│       ├── repository.md           # Repository reference page
│       ├── agent.md                # Bedrock agent reference page
│       ├── api.md                  # API scenario reference page
│       ├── eventbridge.md          # EventBridge scenario reference page
│       ├── graphql.md              # AppSync GraphQL scenario reference page
│       ├── s3.md                   # S3 scenario reference page
│       ├── stream.md               # Stream scenario reference page
│       └── sqs.md                  # SQS scenario reference page
├── templates                       # Main package
│   ├── agent                       # Bedrock agent function handler
│   ├── api                         # API request handler
│   ├── eventbridge                 # EventBridge event handler
│   ├── graphql                     # AppSync GraphQL resolver
│   ├── s3                          # S3 event handler
│   ├── stream                      # DynamoDB stream batch processor
│   ├── sqs                         # SQS message handler
│   ├── queue.py                    # SQS queue interaction
│   └── repository.py               # DynamoDB repository
├── infra                           # AWS CDK infrastructure
│   ├── app.py                      # CDK entry point
│   └── stacks                      # CDK stack definitions
│       ├── agent.py                # Bedrock agent stack
│       ├── api.py                  # ApiGateway stack
│       ├── evetbridge.py           # EventBridge stack
│       ├── graphql.py              # AppSync GraphQL stack
│       ├── s3.py                   # S3 stack
│       ├── stream.py               # DynamoDB Stream stack
│       └── sqs.py                  # SQS stack
└── tests                           # Test folder
    ├── conftest.py                 # Pytest configuration, fixtures, and hooks
    ├── test_repository.py          # Repository tests
    ├── agent                       # Bedrock agent scenario tests
    ├── api                         # API scenario tests
    ├── eventbridge                 # EventBridge scenario tests
    ├── graphql                     # GraphQL scenario tests
    ├── s3                          # S3 scenario tests
    ├── stream                      # DynamoDB Stream scenario tests
    └── sqs                         # SQS scenario tests