Skip to main content

EasySAM

EasySAM is an opinionated YAML-to-SAM generator for modular AWS serverless applications.

It helps you define Lambda functions, API Gateway routes, DynamoDB tables, S3 buckets, SQS queues, Kinesis streams, OpenSearch Serverless collections, and IoT Core authorizers in a compact resources.yaml model, then generate and deploy the resulting SAM stack.

Why EasySAM

  • Simple YAML-first resource definitions
  • Recursive import system (import + local easysam.yaml)
  • Modular app structure with shared common/ code support
  • Built-in validation (inspect schema, inspect cloud)
  • Native support for:
    • Environment variable expansion and .env loading
    • DynamoDB stream triggers from table definitions
    • DynamoDB TTL
    • Lambda Function URLs
    • Prismarine model-driven tables
    • OpenSearch Serverless search collections
    • MQTT/IoT Core custom authorizers
    • Local Lambda execution (no Docker required)

Prerequisites

  • Python 3.12+ (Your local/CI environment version should match the python: option in resources.yaml to ensure dependency compatibility)
  • AWS credentials configured (named profile recommended)
  • AWS SAM CLI 1.138.0+
  • pip 25.1.1+ (used in deployment checks)
  • One of:
    • uv (recommended for project-local workflows)
    • pipx (recommended for global CLI install)
    • pip

Installation

Choose one installation method.

Option A: project-local with uv

uv add --dev easysam

Use as:

uv run easysam --help

Option B: global with pipx

pipx install easysam

Use as:

easysam --help

Option C: global/local with pip

pip install easysam

Quick start (5 minutes)

  1. Create a Python project and initialize EasySAM:
mkdir my-easysam-app
cd my-easysam-app
uv init
uv add --dev easysam
uv run easysam init

For a Prismarine scaffold:

uv run easysam init --prismarine
  1. Validate your resources:
uv run easysam --environment dev inspect schema .
  1. Generate templates:
uv run easysam --environment dev generate .
  1. Deploy to AWS:
uv run easysam --environment dev --aws-profile my-profile deploy . --tag project=easysam-demo
  1. Delete stack when done:
uv run easysam --environment dev --aws-profile my-profile delete --await

For all options:

uv run easysam --help

Local execution

Run your Lambda handlers locally without deploying — no Docker required. EasySAM starts a local HTTP server that mocks API Gateway routing while using real cloud resources (DynamoDB, S3, etc.).

# Start local server (default: http://127.0.0.1:3000)
uv run easysam --environment dev local .

# Custom port and REST API v1 event format (default)
uv run easysam --environment dev local . --port 8080

# Use HTTP API v2 event format
uv run easysam --environment dev local . --event-format v2

# Inject authorization context (simulates authenticated user)
uv run easysam --environment dev local . --auth-context '{"principalId": "dev-user"}'

# Or from a file
uv run easysam --environment dev local . --auth-context auth-context.json

Then call your endpoints:

curl http://127.0.0.1:3000/items

Invoke a single function

For non-HTTP triggers (SQS, Kinesis, DynamoDB streams), invoke a function directly:

# With an event file
uv run easysam --environment dev local . invoke myfunction --event event.json

# With inline JSON
uv run easysam --environment dev local . invoke myfunction --event '{"Records": [...]}'

# With empty event (default)
uv run easysam --environment dev local . invoke myfunction

Minimal resources.yaml

prefix: MyApp

import:
  - backend

EasySAM recursively finds easysam.yaml files under backend/ and merges them.

Local import file format (easysam.yaml)

lambda:
  name: myfunction
  resources:
    tables:
      - MyItem
  integration:
    path: /items
    open: true
    greedy: false

You can also define tables locally:

tables:
  MyItem:
    attributes:
      - name: ItemID
        hash: true

Key concepts

Environment Variables and .env files

EasySAM automatically loads .env files if present in the target directory. It evaluates environment variables using the standard ${MY_VAR} syntax in both global (resources.yaml) and local (easysam.yaml) files immediately after they are loaded.

Global CLI options can also be set via environment variables:

CLI option Environment variable
--environment EASYSAM_ENVIRONMENT
--aws-profile EASYSAM_AWS_PROFILE
--target-region EASYSAM_TARGET_REGION

Explicit CLI flags always take precedence over environment variables.

You can also pass environment variables to your functions directly using the envvars property.

functions:
  myfunc:
    uri: "src/"
    envvars:
      API_URL: "${API_URL}"
      LOG_LEVEL: "DEBUG"

DynamoDB table triggers

Trigger a Lambda directly from table changes:

tables:
  SearchableItem:
    attributes:
      - name: ItemID
        hash: true
    trigger: indexfunc

Advanced trigger configuration:

tables:
  SearchableItem:
    attributes:
      - name: ItemID
        hash: true
    trigger:
      function: indexfunc
      viewtype: new-and-old
      batchsize: 10
      batchwindow: 5
      startingposition: latest

SQS queues (standard and FIFO)

Declare standard queues as null-valued keys, or FIFO queues with fifo: true:

queues:
  notifications:            # standard queue
  orders:
    fifo: true              # FIFO queue (name gets a `.fifo` suffix automatically)
    content_based_deduplication: true

FIFO defaults are applied automatically (ContentBasedDeduplication: true, DeduplicationScope: queue, FifoThroughputLimit: perQueue), and deduplication_scope: messageGroup auto-sets fifo_throughput_limit: perMessageGroupId. FIFO queues work with Lambda polls and send, but cannot be an API Gateway sqs integration target. See the Resource reference for all properties and operational notes (head-of-line blocking, deduplication window, migration).

Conditional resources

Conditional keys are resolved against deploy context (environment, target_region):

buckets:
  ? !Conditional
    key: my-bucket
    environment: prod
    region: eu-west-2
  :
    public: true
    extaccesspolicy: ProdPolicy

Negation is supported using ~ (example: environment: ~prod).

Deployment context overrides

Use a context file for CI/environment-specific patches:

overrides:
  buckets/my-bucket/public: true

Then pass it with:

uv run easysam --environment dev --context-file deploy-context.yaml deploy .

Prismarine integration

prismarine:
  default-base: common
  access-module: common.dynamo_access
  modelling: typed-dict
  tables:
    - package: myobject

Set modelling: pydantic for Pydantic-based generated clients.

MQTT / IoT Core custom authorizer

mqtt:
  authorizer:
    function: mqtt-auth
  topics:
    - channels/*

If a function publishes to IoT topics, add mqtt in function services.

Documentation

Examples

All examples live under example/ and include focused scenarios such as:

  • minimal app bootstrap
  • conditionals and deploy context overrides
  • custom Lambda layers
  • global and local env vars (with .env file support) and plugins
  • DynamoDB TTL (plain + Prismarine)
  • Prismarine TypedDict and Pydantic modelling
  • OpenSearch Serverless + DynamoDB streams
  • Kinesis with multiple S3 destinations

See the full index: example/README.md.

Development

git clone https://github.com/scartill/easysam.git
cd easysam
uv sync
source .venv/bin/activate

Changelog

See CHANGELOG.md.

Support

If you hit an issue:

  1. Search existing issues
  2. Open a new issue with a reproducible example

License

MIT. See LICENSE.

Metadata

Release files for easysam 1.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for easysam 1.14.0
File Size Uploaded Provenance Actions
easysam-1.14.0.tar.gz 386.9 kB With provenance Details for easysam-1.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for easysam 1.14.0
File Interpreter ABI Platform Actions
easysam-1.14.0-py3-none-any.whl Python 3 none any Details for easysam-1.14.0-py3-none-any.whl

Total release size: 436.9 kB

Release files / easysam-1.14.0.tar.gz

Download URL easysam-1.14.0.tar.gz
Size 386.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b2bb8ea52210913e9e8ab834eee049b3e18d73a15f8f97c95a397200413cf9ac
BLAKE2b-256 checksum
How to use checksums
a42ef8c83eb5027568ae97990184ac18113503fcfa532e1b42aa74c3126d7284
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / easysam-1.14.0-py3-none-any.whl

Download URL easysam-1.14.0-py3-none-any.whl
Size 50.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f4024842e0dec7d82b82131597724788ca7fb0cb73399de05a7af7ff57f8df43
BLAKE2b-256 checksum
How to use checksums
1f621fd233762cddb3a0a20f532d7117e4c05497a8f4c314a3c72d142cb4eb3c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for easysam 1.14.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for easysam-1.14.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page