Metadata-Version: 2.4
Name: samrenderer
Version: 0.1.1
Summary: A tool to render SAM templates locally with SAM config overrides
Project-URL: Repository, https://github.com/ryanm101/samrenderer.git
Project-URL: Issues, https://github.com/ryanm101/samrenderer/issues
Maintainer-email: Ryan McLean <ryan1_00@hotmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: AWS,Cloudformation,SAM,Serverless Application Model
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: boto3>=1.40.76
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tomli>=2.3.0
Description-Content-Type: text/markdown

# SAM Template Renderer

A lightweight Python tool to parse, resolve, and render AWS SAM and CloudFormation templates locally.

This tool is designed to help debug complex template logic—specifically Mappings, Conditions, and Substitutions—without needing to deploy to AWS. It resolves intrinsic functions locally and outputs the final "rendered" YAML.

## Features

- Intrinsic Function Resolution: Evaluates `Fn::FindInMap`, `Fn::If`, `Fn::Sub`, `Fn::Join`, `Fn::Select`, `Fn::Split`, and more locally.
- Logic Handling: fully supports boolean logic (`Fn::And`, `Fn::Or`, `Fn::Not`, `Fn::Equals`) to correctly evaluate Condition blocks.
- SAM Config Support: Parses `samconfig.toml` to apply environment-specific `parameter_overrides` automatically.
- Custom YAML Tags: Handles short-form CloudFormation tags (e.g., `!Ref`, `!Sub`, `!GetAtt`) without parsing errors.
- Hybrid Resolution: Mocks runtime values (like Resource IDs) but can optionally fetch real `Fn::ImportValue` data from AWS if a profile is provided.
- Extended Syntax: Supports custom 4th-argument "DefaultValue" syntax for `Fn::FindInMap`.

## Installation

This project is managed with [uv](https://github.com/astral-sh/uv).

```bash
# Clone the repository
git clone git@github.com:ryanm101/samrenderer.git
cd samrenderer

# Install dependencies and sync environment
uv sync
```

## Usage

Run the renderer against a template file. You can optionally specify a `samconfig.toml` environment or an AWS profile.

### Basic Rendering

Resolves parameters using defaults defined in the template.uv run sam-render template.yaml

### Using SAM Config (Recommended)

Applies parameters from `[<env>.deploy.parameters]` in `samconfig.toml`.

```bash
uv run sam-render examples/template.yaml --config examples/samconfig.toml --env dev
```

### Fetching Real Exports

By default, `Fn::ImportValue` returns a mock string. Provide an AWS profile to fetch real values from CloudFormation exports.

```bash
uv run sam-render template.yaml --config samconfig.toml --env dev --profile my-aws-profile
```

## Supported Functions

| Category | Function          | Status | Notes                                                               |
|----------|-------------------|--------|---------------------------------------------------------------------|
| Core     | `Ref`             | ✅      | Resolves Parameters/Pseudo-params; mocks Resources.                 |
|          | `Fn::GetAtt`      | ⚠️     | Returns mock string `mock-resource-attr`.                           |
|          | `Fn::ImportValue` | ✅      | Fetches from AWS if `--profile` is set, otherwise mocks.            |
| Logic    | `Fn::If`          | ✅      | Full support.                                                       |
|          | `Fn::Equals`      | ✅      | Full support.                                                       |
|          | `Fn::Not`         | ✅      | Full support.                                                       |
|          | `Fn::And / Or`    | ✅      | Full support.                                                       |
|          | `Condition`       | ✅      | Resolves Condition keys in dictionaries.                            |
| Maps     | `Fn::FindInMap`   | ✅      | Supports standard 3-arg and custom 4-arg (DefaultValue) syntax.     |
| String   | `Fn::Sub`         | ✅      | Supports String and Key-Value map interpolation.                    |
|          | `Fn::Join`        | ✅      | Full support.                                                       |
|          | `Fn::Split`       | ✅      | Full support.                                                       |
|          | `Fn::Select`      | ✅      | Full support.                                                       |
|          | `Fn::Base64`      | ⚠️     | ️Returns readable string `[Base64: ...]` instead of encoding.       |
|          | `Fn::GetAZs`      | ⚠️     | Returns mock list based on Region (e.g., `us-east-1a`, `1b`, `1c`). |

## Development & Testing

Tests are written using pytest.

```bash
# Run all tests
uv run pytest
```
