samwich-cli 0.6.0

A CLI tool to streamline AWS SAM deployments for Python Lambda functions by managing dependencies, executing sam build, and maintaining consistent folder structures.

SAMWICH CLI

A sandwich :sandwich: for sam build

SAMWICH CLI is a tool that simplifies working with AWS Serverless Application Model (SAM) deployments, particularly focusing on dependency management and build processes for Python Lambda functions and layers.

Note: This project is in early development and may not be fully functional.

Table of Contents

• Inspiration
• Installation
• Requirements
• Features
• Basic Usage
• Example (with layers)
• Example (without layers)
• License
• Contributing
• Development
• Code Quality

Inspiration

Many python projects do not use requirements.txt files, but instead use pyproject.toml with poetry or uv. This tool is designed to help those projects by copying the generated requirements.txt to the appropriate locations for AWS Lambda functions and layers.

Also, using absolute python imports from the project root is not currently possible with AWS SAM (see https://github.com/aws/aws-sam-cli/issues/6593). This tool helps to maintain a consistent folder structure for your functions and layers, so the lambda functions can be individually packaged with the same folder structure as they are developed.

Installation

pipx install samwich-cli

Requirements

• Python 3.9 or higher

Features

The SAMWICH CLI:

1. Copies your requirements.txt file to the appropriate locations for Lambda functions and layers.
2. Executes sam build to build your AWS resources.
3. Updates the folder structure of your functions and layers to maintain consistency.

Basic Usage

uv export \
  --locked \
  --output-file requirements.txt

samwich-cli --requirements requirements.txt --template-file template.yaml

Options

• --requirements: Path to your Python requirements.txt file. Defaults to requirements.txt in the current directory.
• --template-file: Path to your AWS SAM template file. Defaults to template.yaml in the current directory.
• --sam-args: Additional arguments to pass to sam build. For example, --sam-args "--debug --use-container".
• --debug: Enable debug logging

Environment Variables

• SAMWICH_WORKSPACE: Override the default workspace root (defaults to git repository root)
• SAMWICH_TEMP: Override the default temporary directory.

Example (with layers)

Project Structure

my-project/
├── src/
│   ├── lib/
│   │    └── utils.py
│   ├── sender/
│   │   └── app.py
│   └── receiver/
│       └── app.py
├── pyproject.toml
└── uv.lock

SAM Template

AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: My SAM Application

Resources:
  SenderFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: sender.app.lambda_handler
      Runtime: python3.12
      CodeUri: src/sender/
      Layers:
        - !Ref MyLayer

  ReceiverFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: receiver.app.lambda_handler
      Runtime: python3.12
      CodeUri: src/receiver/
      Layers:
        - !Ref MyLayer

  MyLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: MyLayer
      ContentUri: lib/
      CompatibleRuntimes:
        - python3.12
      Metadata:
        BuildMethod: python3.12

SAMWICH CLI

uv export \
  --locked \
  --output-file requirements.txt
samwich-cli --source-dir src --sam-args "--cached"

Resulting Structure

.aws-sam/
├── build/
│   ├── SenderFunction/
│   │   └── sender/
│   |       └── app.py
│   ├── ReceiverFunction/
│   │   └── receiver/
|   |       └── app.py
│   └── MyLayer/
│       └── python/
│           ├── requirements.txt
│           ├── < project dependencies >
│           └── lib/
│               └── utils.py

Example (without layers)

Project Structure

my-project/
├── src/
│   ├── sender/
│   │   └── app.py
│   └── receiver/
│       └── app.py
├── pyproject.toml
└── uv.lock

SAM Template

AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: My SAM Application
Resources:
  SenderFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src.sender.app.lambda_handler
      Runtime: python3.12
      CodeUri: src/sender/

  ReceiverFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src.receiver.app.lambda_handler
      Runtime: python3.12
      CodeUri: src/receiver/

Resulting Structure

.aws-sam/
├── build/
│   ├── SenderFunction/
│   │   ├── requirements.txt
│   │   ├── < project dependencies >
│   │   └── src/
│   |       └── sender/
│   |           └── app.py
│   └── ReceiverFunction/
│       ├── requirements.txt
|       ├── < project dependencies >
|       └── src/
│           └── receiver/
│               └── app.py

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development

1. Clone the repository
2. Install development dependencies with your package manager of choice
3. Install pre-commit hooks: pre-commit install

Code Quality

This project uses pre-commit hooks for code quality, including:

• Ruff for linting and formatting
• pycln for removing unused imports
• Various pre-commit hooks for file consistency