Flask support!

.github/workflows/python-ci.yml

@@ -27,8 +27,6 @@ jobs:
  run: uv sync
  - name: Install viceroy
  run: cargo install --git https://github.com/fastly/Viceroy.git --branch sunfishcode/sync-wit viceroy
- - name: Build WebAssembly component
- run: make app.wasm
  - name: Install dependencies
  run: uv sync --extra dev --extra test
  - name: Check formatting

.gitignore

@@ -5,4 +5,7 @@ uv.lock
 
 /stubs/
 __pycache__
-app.wasm
+
+# Build artifacts
+/build/
+*.wasm

Makefile

@@ -1,18 +1,56 @@
-all: app.wasm
+# Fastly Compute Python SDK
 
+# Configuration
 STUBS_DIR := stubs
+BUILD_DIR := build
+EXAMPLES_DIR := examples
 
-app.wasm: wit/viceroy.wit wit/deps/fastly/compute.wit app.py
-	rm -rf ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy bindings ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy componentize app -o app.wasm
+# Define all available examples (add new ones here)
+EXAMPLES := wit-bottle flask-app
 
-serve: app.wasm
-	viceroy serve app.wasm
+# Default example for serve target
+EXAMPLE ?= wit-bottle
+WASM_FILE := $(BUILD_DIR)/$(EXAMPLE).wasm
 
-test: app.wasm
+# Generate WASM file paths for all examples
+EXAMPLE_WASMS := $(foreach example,$(EXAMPLES),$(BUILD_DIR)/$(example).wasm)
+
+# Default target builds all examples
+all: $(EXAMPLE_WASMS)
+
+# Pattern rule for building any example
+$(BUILD_DIR)/%.wasm: $(EXAMPLES_DIR)/%.py wit/viceroy.wit wit/deps/fastly/compute.wit | $(BUILD_DIR)
+	@echo "Building $* example..."
+	rm -rf $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy bindings $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy componentize $* -p $(EXAMPLES_DIR) -p . -o $@
+
+# Create build directory
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Serve the specified example (default: wit-bottle)
+serve: $(WASM_FILE)
+	@echo "Serving $(EXAMPLE) example on http://127.0.0.1:7676"
+	viceroy serve $(WASM_FILE)
+
+# Test all examples (requires all WASM files to be built)
+test: $(EXAMPLE_WASMS)
 	uv run --extra test pytest
 
+# List available examples
+list-examples:
+	@echo "Available examples:"
+	@for example in $(EXAMPLES); do echo " $$example"; done
+
+# Build all examples (alias for 'all')
+build-all: all
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR) $(STUBS_DIR)
+
+# Development tools
 lint:
 	uv run --extra dev ruff check .
 
@@ -25,4 +63,29 @@ format:
 format-check:
 	uv run --extra dev ruff format --check .
 
-.PHONY: all serve test lint format format-check
+# Help target
+help:
+	@echo "Fastly Compute Python SDK"
+	@echo ""
+	@echo "Targets:"
+	@echo " all Build all examples"
+	@echo " serve [EXAMPLE=name] Serve example (default: $(EXAMPLE))"
+	@echo " test Run integration tests (builds all examples)"
+	@echo " build-all Build all examples (alias for 'all')"
+	@echo " list-examples List available examples"
+	@echo " clean Clean build artifacts"
+	@echo " lint Run linter"
+	@echo " lint-fix Run linter with auto-fix"
+	@echo " format Format code"
+	@echo " format-check Check code formatting"
+	@echo ""
+	@echo "Examples:"
+	@echo " make # Build all examples"
+	@echo " make serve # Serve wit-bottle example"
+	@echo " make serve EXAMPLE=flask-app # Serve flask-app example"
+	@echo " make build/flask-app.wasm # Build specific example"
+	@echo ""
+	@echo "Available examples: $(EXAMPLES)"
+
+.PHONY: all serve test list-examples build-all clean lint lint-fix format format-check help
+

README.md

@@ -1,65 +1,68 @@
-This is the experimental beginning of a Python SDK for [Fastly
-Compute](https://www.fastly.com/products/edge-compute).
+# Fastly Compute Python SDK
 
-# Status
+Experimental Python SDK for [Fastly Compute](https://www.fastly.com/products/edge-compute) services.
 
-Currently, this demonstrates…
+## Features
 
-* Building arbitrary pure Python into a component
-* Creating Python bindings from Fastly's WIT files
-* Hosting arbitrary web frameworks by adapting Fastly's API, through those
- bindings, to WSGI
+- **Multiple Framework Support**: Examples with Bottle, Flask, and more
+- **WIT Bindings**: Auto-generated Python bindings from Fastly's WIT files
+- **WSGI Compatibility**: Host any WSGI-compatible web framework
+- **Testing Framework**: Comprehensive viceroy-based integration testing
+- **Type Safety**: Full type hints and IDE support
 
-# Caveats
+## Quick Start
 
-* Any native Python modules need to be compiled against WASI. Few are at the
- moment. However, [Joel has done
- some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
- aren't extensive.
-* Most popular web frameworks we tried [wouldn't work because they depended on
- zlib](https://github.com/bytecodealliance/componentize-py/issues/96) and other
- native-code compression stdlibs which haven't been compiled against WASI yet.
- Moving componentize-py to a new Python may help, as [WASIp1 is now a Tier 2
- supported platform](https://peps.python.org/pep-0011/#tier-2).
+### Build and Run
+```bash
+make serve # Serve default example (Bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
 
-# Install Dependencies
+Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info
 
-1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
-2. Install [Viceroy](https://github.com/fastly/Viceroy). Make sure you have [a
- branch with up-to-date WIT
- files](https://github.com/fastly/Viceroy/tree/sunfishcode/sync-wit) so it can
- run components.
+### Available Examples
 
-# Build and Run
+```bash
+make list-examples # List all examples
+make build-all # Build all examples
+```
 
-1. `make serve`
-2. Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info in a browser.
+### Testing
+```bash
+make test # Run integration tests
+```
 
-You are seeing Bottle, a simple Python web framework, run on a Fastly Compute
-worker!
+## Development
 
-# Testing
+### Code Quality
+```bash
+make format # Format code
+make lint # Run linter
+make lint-fix # Auto-fix linting issues
+```
 
+### Building Examples
 ```bash
-# Install dependencies and run tests
-uv sync --extra dev --extra test
-make test
+make build/my-app.wasm # Build specific example
+make clean # Clean build artifacts
 ```
 
-The tests automatically build the WebAssembly component, start viceroy, and verify all endpoints work correctly with the WIT APIs.
+## Status
 
-# Development
+Currently demonstrates:
+- Building pure Python into WebAssembly components
+- Creating Python bindings from Fastly's WIT files
+- Hosting web frameworks by adapting Fastly's API to WSGI
+- Comprehensive testing with viceroy integration
 
-```bash
-# Format code
-make format
+## Caveats
 
-# Check formatting
-make format-check
+- Any native Python modules need to be compiled against WASI. Few are at the
+ moment. However, [Joel has done
+ some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
+ aren't extensive.
 
-# Run linting
-make lint
+## Prerequisites
 
-# Run linting and apply automatic fixes
-make lint-fix
-```
+1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install [Viceroy](https://github.com/fastly/Viceroy) with component support

examples/README.md

@@ -0,0 +1,73 @@
+# Fastly Compute Python Examples
+
+This directory contains example applications demonstrating different approaches to building Fastly Compute services with Python.
+
+## Available Examples
+
+### `wit-bottle.py`
+- **Framework**: Bottle (lightweight WSGI framework)
+- **Features**: Basic routing, JSON responses, WIT API integration
+- **Use Case**: Simple services, proof-of-concept applications
+
+### `flask-app.py`
+- **Framework**: Flask (popular Python web framework)
+- **Features**: Flask routing, request handling, error handling
+- **Use Case**: More complex applications, familiar Flask patterns
+
+## Building and Running Examples
+
+### Build a Specific Example
+```bash
+make build/flask-app.wasm # Build Flask example
+make build/wit-bottle.wasm # Build Bottle example
+```
+
+### Serve an Example
+```bash
+make serve # Serve default (wit-bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
+
+### Build All Examples
+```bash
+make build-all
+```
+
+### List Available Examples
+```bash
+make list-examples
+```
+
+## Testing Examples
+
+The integration tests use the default example (wit-bottle). To test other examples:
+
+```bash
+# Update the test to use a different example
+EXAMPLE=flask-app make test
+```
+
+## Creating New Examples
+
+1. Create a new `.py` file in this directory
+2. Implement your WSGI application
+3. Include the `serve_wsgi_request` function and `HttpIncoming` class
+4. Build with `make build/your-example.wasm`
+5. Test with `make serve EXAMPLE=your-example`
+
+## Framework Requirements
+
+All examples must:
+- Be WSGI-compatible applications
+- Include the WIT integration boilerplate (`serve_wsgi_request`, `HttpIncoming`)
+- Handle the standard test endpoints for integration tests:
+ - `/hello/<name>` - Returns "Hello {name}!"
+ - `/info` - Returns JSON with service info and WIT data
+ - `/error` - Raises an exception for error testing
+
+## Dependencies
+
+Examples may use different web frameworks, but they all rely on:
+- `wit_world` - Generated WIT bindings
+- `componentize-py` - Python to WebAssembly compilation
+- Framework-specific dependencies (bottle, flask, etc.)

.github/workflows/python-ci.yml

@@ -27,8 +27,6 @@ jobs:
  run: uv sync
  - name: Install viceroy
  run: cargo install --git https://github.com/fastly/Viceroy.git --branch sunfishcode/sync-wit viceroy
- - name: Build WebAssembly component
- run: make app.wasm
  - name: Install dependencies
  run: uv sync --extra dev --extra test
  - name: Check formatting

.gitignore

@@ -5,4 +5,7 @@ uv.lock
 
 /stubs/
 __pycache__
-app.wasm
+
+# Build artifacts
+/build/
+*.wasm

Makefile

@@ -1,18 +1,56 @@
-all: app.wasm
+# Fastly Compute Python SDK
 
+# Configuration
 STUBS_DIR := stubs
+BUILD_DIR := build
+EXAMPLES_DIR := examples
 
-app.wasm: wit/viceroy.wit wit/deps/fastly/compute.wit app.py
-	rm -rf ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy bindings ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy componentize app -o app.wasm
+# Define all available examples (add new ones here)
+EXAMPLES := wit-bottle flask-app
 
-serve: app.wasm
-	viceroy serve app.wasm
+# Default example for serve target
+EXAMPLE ?= wit-bottle
+WASM_FILE := $(BUILD_DIR)/$(EXAMPLE).wasm
 
-test: app.wasm
+# Generate WASM file paths for all examples
+EXAMPLE_WASMS := $(foreach example,$(EXAMPLES),$(BUILD_DIR)/$(example).wasm)
+
+# Default target builds all examples
+all: $(EXAMPLE_WASMS)
+
+# Pattern rule for building any example
+$(BUILD_DIR)/%.wasm: $(EXAMPLES_DIR)/%.py wit/viceroy.wit wit/deps/fastly/compute.wit | $(BUILD_DIR)
+	@echo "Building $* example..."
+	rm -rf $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy bindings $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy componentize $* -p $(EXAMPLES_DIR) -p . -o $@
+
+# Create build directory
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Serve the specified example (default: wit-bottle)
+serve: $(WASM_FILE)
+	@echo "Serving $(EXAMPLE) example on http://127.0.0.1:7676"
+	viceroy serve $(WASM_FILE)
+
+# Test all examples (requires all WASM files to be built)
+test: $(EXAMPLE_WASMS)
 	uv run --extra test pytest
 
+# List available examples
+list-examples:
+	@echo "Available examples:"
+	@for example in $(EXAMPLES); do echo " $$example"; done
+
+# Build all examples (alias for 'all')
+build-all: all
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR) $(STUBS_DIR)
+
+# Development tools
 lint:
 	uv run --extra dev ruff check .
 
@@ -25,4 +63,29 @@ format:
 format-check:
 	uv run --extra dev ruff format --check .
 
-.PHONY: all serve test lint format format-check
+# Help target
+help:
+	@echo "Fastly Compute Python SDK"
+	@echo ""
+	@echo "Targets:"
+	@echo " all Build all examples"
+	@echo " serve [EXAMPLE=name] Serve example (default: $(EXAMPLE))"
+	@echo " test Run integration tests (builds all examples)"
+	@echo " build-all Build all examples (alias for 'all')"
+	@echo " list-examples List available examples"
+	@echo " clean Clean build artifacts"
+	@echo " lint Run linter"
+	@echo " lint-fix Run linter with auto-fix"
+	@echo " format Format code"
+	@echo " format-check Check code formatting"
+	@echo ""
+	@echo "Examples:"
+	@echo " make # Build all examples"
+	@echo " make serve # Serve wit-bottle example"
+	@echo " make serve EXAMPLE=flask-app # Serve flask-app example"
+	@echo " make build/flask-app.wasm # Build specific example"
+	@echo ""
+	@echo "Available examples: $(EXAMPLES)"
+
+.PHONY: all serve test list-examples build-all clean lint lint-fix format format-check help
+

README.md

@@ -1,65 +1,68 @@
-This is the experimental beginning of a Python SDK for [Fastly
-Compute](https://www.fastly.com/products/edge-compute).
+# Fastly Compute Python SDK
 
-# Status
+Experimental Python SDK for [Fastly Compute](https://www.fastly.com/products/edge-compute) services.
 
-Currently, this demonstrates…
+## Features
 
-* Building arbitrary pure Python into a component
-* Creating Python bindings from Fastly's WIT files
-* Hosting arbitrary web frameworks by adapting Fastly's API, through those
- bindings, to WSGI
+- **Multiple Framework Support**: Examples with Bottle, Flask, and more
+- **WIT Bindings**: Auto-generated Python bindings from Fastly's WIT files
+- **WSGI Compatibility**: Host any WSGI-compatible web framework
+- **Testing Framework**: Comprehensive viceroy-based integration testing
+- **Type Safety**: Full type hints and IDE support
 
-# Caveats
+## Quick Start
 
-* Any native Python modules need to be compiled against WASI. Few are at the
- moment. However, [Joel has done
- some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
- aren't extensive.
-* Most popular web frameworks we tried [wouldn't work because they depended on
- zlib](https://github.com/bytecodealliance/componentize-py/issues/96) and other
- native-code compression stdlibs which haven't been compiled against WASI yet.
- Moving componentize-py to a new Python may help, as [WASIp1 is now a Tier 2
- supported platform](https://peps.python.org/pep-0011/#tier-2).
+### Build and Run
+```bash
+make serve # Serve default example (Bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
 
-# Install Dependencies
+Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info
 
-1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
-2. Install [Viceroy](https://github.com/fastly/Viceroy). Make sure you have [a
- branch with up-to-date WIT
- files](https://github.com/fastly/Viceroy/tree/sunfishcode/sync-wit) so it can
- run components.
+### Available Examples
 
-# Build and Run
+```bash
+make list-examples # List all examples
+make build-all # Build all examples
+```
 
-1. `make serve`
-2. Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info in a browser.
+### Testing
+```bash
+make test # Run integration tests
+```
 
-You are seeing Bottle, a simple Python web framework, run on a Fastly Compute
-worker!
+## Development
 
-# Testing
+### Code Quality
+```bash
+make format # Format code
+make lint # Run linter
+make lint-fix # Auto-fix linting issues
+```
 
+### Building Examples
 ```bash
-# Install dependencies and run tests
-uv sync --extra dev --extra test
-make test
+make build/my-app.wasm # Build specific example
+make clean # Clean build artifacts
 ```
 
-The tests automatically build the WebAssembly component, start viceroy, and verify all endpoints work correctly with the WIT APIs.
+## Status
 
-# Development
+Currently demonstrates:
+- Building pure Python into WebAssembly components
+- Creating Python bindings from Fastly's WIT files
+- Hosting web frameworks by adapting Fastly's API to WSGI
+- Comprehensive testing with viceroy integration
 
-```bash
-# Format code
-make format
+## Caveats
 
-# Check formatting
-make format-check
+- Any native Python modules need to be compiled against WASI. Few are at the
+ moment. However, [Joel has done
+ some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
+ aren't extensive.
 
-# Run linting
-make lint
+## Prerequisites
 
-# Run linting and apply automatic fixes
-make lint-fix
-```
+1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install [Viceroy](https://github.com/fastly/Viceroy) with component support

examples/README.md

@@ -0,0 +1,73 @@
+# Fastly Compute Python Examples
+
+This directory contains example applications demonstrating different approaches to building Fastly Compute services with Python.
+
+## Available Examples
+
+### `wit-bottle.py`
+- **Framework**: Bottle (lightweight WSGI framework)
+- **Features**: Basic routing, JSON responses, WIT API integration
+- **Use Case**: Simple services, proof-of-concept applications
+
+### `flask-app.py`
+- **Framework**: Flask (popular Python web framework)
+- **Features**: Flask routing, request handling, error handling
+- **Use Case**: More complex applications, familiar Flask patterns
+
+## Building and Running Examples
+
+### Build a Specific Example
+```bash
+make build/flask-app.wasm # Build Flask example
+make build/wit-bottle.wasm # Build Bottle example
+```
+
+### Serve an Example
+```bash
+make serve # Serve default (wit-bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
+
+### Build All Examples
+```bash
+make build-all
+```
+
+### List Available Examples
+```bash
+make list-examples
+```
+
+## Testing Examples
+
+The integration tests use the default example (wit-bottle). To test other examples:
+
+```bash
+# Update the test to use a different example
+EXAMPLE=flask-app make test
+```
+
+## Creating New Examples
+
+1. Create a new `.py` file in this directory
+2. Implement your WSGI application
+3. Include the `serve_wsgi_request` function and `HttpIncoming` class
+4. Build with `make build/your-example.wasm`
+5. Test with `make serve EXAMPLE=your-example`
+
+## Framework Requirements
+
+All examples must:
+- Be WSGI-compatible applications
+- Include the WIT integration boilerplate (`serve_wsgi_request`, `HttpIncoming`)
+- Handle the standard test endpoints for integration tests:
+ - `/hello/<name>` - Returns "Hello {name}!"
+ - `/info` - Returns JSON with service info and WIT data
+ - `/error` - Raises an exception for error testing
+
+## Dependencies
+
+Examples may use different web frameworks, but they all rely on:
+- `wit_world` - Generated WIT bindings
+- `componentize-py` - Python to WebAssembly compilation
+- Framework-specific dependencies (bottle, flask, etc.)

.github/workflows/python-ci.yml

@@ -27,8 +27,6 @@ jobs:
  run: uv sync
  - name: Install viceroy
  run: cargo install --git https://github.com/fastly/Viceroy.git --branch sunfishcode/sync-wit viceroy
- - name: Build WebAssembly component
- run: make app.wasm
  - name: Install dependencies
  run: uv sync --extra dev --extra test
  - name: Check formatting

.gitignore

@@ -5,4 +5,7 @@ uv.lock
 
 /stubs/
 __pycache__
-app.wasm
+
+# Build artifacts
+/build/
+*.wasm

Makefile

@@ -1,18 +1,56 @@
-all: app.wasm
+# Fastly Compute Python SDK
 
+# Configuration
 STUBS_DIR := stubs
+BUILD_DIR := build
+EXAMPLES_DIR := examples
 
-app.wasm: wit/viceroy.wit wit/deps/fastly/compute.wit app.py
-	rm -rf ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy bindings ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy componentize app -o app.wasm
+# Define all available examples (add new ones here)
+EXAMPLES := wit-bottle flask-app
 
-serve: app.wasm
-	viceroy serve app.wasm
+# Default example for serve target
+EXAMPLE ?= wit-bottle
+WASM_FILE := $(BUILD_DIR)/$(EXAMPLE).wasm
 
-test: app.wasm
+# Generate WASM file paths for all examples
+EXAMPLE_WASMS := $(foreach example,$(EXAMPLES),$(BUILD_DIR)/$(example).wasm)
+
+# Default target builds all examples
+all: $(EXAMPLE_WASMS)
+
+# Pattern rule for building any example
+$(BUILD_DIR)/%.wasm: $(EXAMPLES_DIR)/%.py wit/viceroy.wit wit/deps/fastly/compute.wit | $(BUILD_DIR)
+	@echo "Building $* example..."
+	rm -rf $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy bindings $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy componentize $* -p $(EXAMPLES_DIR) -p . -o $@
+
+# Create build directory
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Serve the specified example (default: wit-bottle)
+serve: $(WASM_FILE)
+	@echo "Serving $(EXAMPLE) example on http://127.0.0.1:7676"
+	viceroy serve $(WASM_FILE)
+
+# Test all examples (requires all WASM files to be built)
+test: $(EXAMPLE_WASMS)
 	uv run --extra test pytest
 
+# List available examples
+list-examples:
+	@echo "Available examples:"
+	@for example in $(EXAMPLES); do echo " $$example"; done
+
+# Build all examples (alias for 'all')
+build-all: all
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR) $(STUBS_DIR)
+
+# Development tools
 lint:
 	uv run --extra dev ruff check .
 
@@ -25,4 +63,29 @@ format:
 format-check:
 	uv run --extra dev ruff format --check .
 
-.PHONY: all serve test lint format format-check
+# Help target
+help:
+	@echo "Fastly Compute Python SDK"
+	@echo ""
+	@echo "Targets:"
+	@echo " all Build all examples"
+	@echo " serve [EXAMPLE=name] Serve example (default: $(EXAMPLE))"
+	@echo " test Run integration tests (builds all examples)"
+	@echo " build-all Build all examples (alias for 'all')"
+	@echo " list-examples List available examples"
+	@echo " clean Clean build artifacts"
+	@echo " lint Run linter"
+	@echo " lint-fix Run linter with auto-fix"
+	@echo " format Format code"
+	@echo " format-check Check code formatting"
+	@echo ""
+	@echo "Examples:"
+	@echo " make # Build all examples"
+	@echo " make serve # Serve wit-bottle example"
+	@echo " make serve EXAMPLE=flask-app # Serve flask-app example"
+	@echo " make build/flask-app.wasm # Build specific example"
+	@echo ""
+	@echo "Available examples: $(EXAMPLES)"
+
+.PHONY: all serve test list-examples build-all clean lint lint-fix format format-check help
+

README.md

@@ -1,65 +1,68 @@
-This is the experimental beginning of a Python SDK for [Fastly
-Compute](https://www.fastly.com/products/edge-compute).
+# Fastly Compute Python SDK
 
-# Status
+Experimental Python SDK for [Fastly Compute](https://www.fastly.com/products/edge-compute) services.
 
-Currently, this demonstrates…
+## Features
 
-* Building arbitrary pure Python into a component
-* Creating Python bindings from Fastly's WIT files
-* Hosting arbitrary web frameworks by adapting Fastly's API, through those
- bindings, to WSGI
+- **Multiple Framework Support**: Examples with Bottle, Flask, and more
+- **WIT Bindings**: Auto-generated Python bindings from Fastly's WIT files
+- **WSGI Compatibility**: Host any WSGI-compatible web framework
+- **Testing Framework**: Comprehensive viceroy-based integration testing
+- **Type Safety**: Full type hints and IDE support
 
-# Caveats
+## Quick Start
 
-* Any native Python modules need to be compiled against WASI. Few are at the
- moment. However, [Joel has done
- some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
- aren't extensive.
-* Most popular web frameworks we tried [wouldn't work because they depended on
- zlib](https://github.com/bytecodealliance/componentize-py/issues/96) and other
- native-code compression stdlibs which haven't been compiled against WASI yet.
- Moving componentize-py to a new Python may help, as [WASIp1 is now a Tier 2
- supported platform](https://peps.python.org/pep-0011/#tier-2).
+### Build and Run
+```bash
+make serve # Serve default example (Bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
 
-# Install Dependencies
+Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info
 
-1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
-2. Install [Viceroy](https://github.com/fastly/Viceroy). Make sure you have [a
- branch with up-to-date WIT
- files](https://github.com/fastly/Viceroy/tree/sunfishcode/sync-wit) so it can
- run components.
+### Available Examples
 
-# Build and Run
+```bash
+make list-examples # List all examples
+make build-all # Build all examples
+```
 
-1. `make serve`
-2. Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info in a browser.
+### Testing
+```bash
+make test # Run integration tests
+```
 
-You are seeing Bottle, a simple Python web framework, run on a Fastly Compute
-worker!
+## Development
 
-# Testing
+### Code Quality
+```bash
+make format # Format code
+make lint # Run linter
+make lint-fix # Auto-fix linting issues
+```
 
+### Building Examples
 ```bash
-# Install dependencies and run tests
-uv sync --extra dev --extra test
-make test
+make build/my-app.wasm # Build specific example
+make clean # Clean build artifacts
 ```
 
-The tests automatically build the WebAssembly component, start viceroy, and verify all endpoints work correctly with the WIT APIs.
+## Status
 
-# Development
+Currently demonstrates:
+- Building pure Python into WebAssembly components
+- Creating Python bindings from Fastly's WIT files
+- Hosting web frameworks by adapting Fastly's API to WSGI
+- Comprehensive testing with viceroy integration
 
-```bash
-# Format code
-make format
+## Caveats
 
-# Check formatting
-make format-check
+- Any native Python modules need to be compiled against WASI. Few are at the
+ moment. However, [Joel has done
+ some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
+ aren't extensive.
 
-# Run linting
-make lint
+## Prerequisites
 
-# Run linting and apply automatic fixes
-make lint-fix
-```
+1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install [Viceroy](https://github.com/fastly/Viceroy) with component support

examples/README.md

@@ -0,0 +1,73 @@
+# Fastly Compute Python Examples
+
+This directory contains example applications demonstrating different approaches to building Fastly Compute services with Python.
+
+## Available Examples
+
+### `wit-bottle.py`
+- **Framework**: Bottle (lightweight WSGI framework)
+- **Features**: Basic routing, JSON responses, WIT API integration
+- **Use Case**: Simple services, proof-of-concept applications
+
+### `flask-app.py`
+- **Framework**: Flask (popular Python web framework)
+- **Features**: Flask routing, request handling, error handling
+- **Use Case**: More complex applications, familiar Flask patterns
+
+## Building and Running Examples
+
+### Build a Specific Example
+```bash
+make build/flask-app.wasm # Build Flask example
+make build/wit-bottle.wasm # Build Bottle example
+```
+
+### Serve an Example
+```bash
+make serve # Serve default (wit-bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
+
+### Build All Examples
+```bash
+make build-all
+```
+
+### List Available Examples
+```bash
+make list-examples
+```
+
+## Testing Examples
+
+The integration tests use the default example (wit-bottle). To test other examples:
+
+```bash
+# Update the test to use a different example
+EXAMPLE=flask-app make test
+```
+
+## Creating New Examples
+
+1. Create a new `.py` file in this directory
+2. Implement your WSGI application
+3. Include the `serve_wsgi_request` function and `HttpIncoming` class
+4. Build with `make build/your-example.wasm`
+5. Test with `make serve EXAMPLE=your-example`
+
+## Framework Requirements
+
+All examples must:
+- Be WSGI-compatible applications
+- Include the WIT integration boilerplate (`serve_wsgi_request`, `HttpIncoming`)
+- Handle the standard test endpoints for integration tests:
+ - `/hello/<name>` - Returns "Hello {name}!"
+ - `/info` - Returns JSON with service info and WIT data
+ - `/error` - Raises an exception for error testing
+
+## Dependencies
+
+Examples may use different web frameworks, but they all rely on:
+- `wit_world` - Generated WIT bindings
+- `componentize-py` - Python to WebAssembly compilation
+- Framework-specific dependencies (bottle, flask, etc.)

.github/workflows/python-ci.yml

@@ -27,8 +27,6 @@ jobs:
  run: uv sync
  - name: Install viceroy
  run: cargo install --git https://github.com/fastly/Viceroy.git --branch sunfishcode/sync-wit viceroy
- - name: Build WebAssembly component
- run: make app.wasm
  - name: Install dependencies
  run: uv sync --extra dev --extra test
  - name: Check formatting

.gitignore

@@ -5,4 +5,7 @@ uv.lock
 
 /stubs/
 __pycache__
-app.wasm
+
+# Build artifacts
+/build/
+*.wasm

Makefile

@@ -1,18 +1,56 @@
-all: app.wasm
+# Fastly Compute Python SDK
 
+# Configuration
 STUBS_DIR := stubs
+BUILD_DIR := build
+EXAMPLES_DIR := examples
 
-app.wasm: wit/viceroy.wit wit/deps/fastly/compute.wit app.py
-	rm -rf ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy bindings ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy componentize app -o app.wasm
+# Define all available examples (add new ones here)
+EXAMPLES := wit-bottle flask-app
 
-serve: app.wasm
-	viceroy serve app.wasm
+# Default example for serve target
+EXAMPLE ?= wit-bottle
+WASM_FILE := $(BUILD_DIR)/$(EXAMPLE).wasm
 
-test: app.wasm
+# Generate WASM file paths for all examples
+EXAMPLE_WASMS := $(foreach example,$(EXAMPLES),$(BUILD_DIR)/$(example).wasm)
+
+# Default target builds all examples
+all: $(EXAMPLE_WASMS)
+
+# Pattern rule for building any example
+$(BUILD_DIR)/%.wasm: $(EXAMPLES_DIR)/%.py wit/viceroy.wit wit/deps/fastly/compute.wit | $(BUILD_DIR)
+	@echo "Building $* example..."
+	rm -rf $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy bindings $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy componentize $* -p $(EXAMPLES_DIR) -p . -o $@
+
+# Create build directory
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Serve the specified example (default: wit-bottle)
+serve: $(WASM_FILE)
+	@echo "Serving $(EXAMPLE) example on http://127.0.0.1:7676"
+	viceroy serve $(WASM_FILE)
+
+# Test all examples (requires all WASM files to be built)
+test: $(EXAMPLE_WASMS)
 	uv run --extra test pytest
 
+# List available examples
+list-examples:
+	@echo "Available examples:"
+	@for example in $(EXAMPLES); do echo " $$example"; done
+
+# Build all examples (alias for 'all')
+build-all: all
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR) $(STUBS_DIR)
+
+# Development tools
 lint:
 	uv run --extra dev ruff check .
 
@@ -25,4 +63,29 @@ format:
 format-check:
 	uv run --extra dev ruff format --check .
 
-.PHONY: all serve test lint format format-check
+# Help target
+help:
+	@echo "Fastly Compute Python SDK"
+	@echo ""
+	@echo "Targets:"
+	@echo " all Build all examples"
+	@echo " serve [EXAMPLE=name] Serve example (default: $(EXAMPLE))"
+	@echo " test Run integration tests (builds all examples)"
+	@echo " build-all Build all examples (alias for 'all')"
+	@echo " list-examples List available examples"
+	@echo " clean Clean build artifacts"
+	@echo " lint Run linter"
+	@echo " lint-fix Run linter with auto-fix"
+	@echo " format Format code"
+	@echo " format-check Check code formatting"
+	@echo ""
+	@echo "Examples:"
+	@echo " make # Build all examples"
+	@echo " make serve # Serve wit-bottle example"
+	@echo " make serve EXAMPLE=flask-app # Serve flask-app example"
+	@echo " make build/flask-app.wasm # Build specific example"
+	@echo ""
+	@echo "Available examples: $(EXAMPLES)"
+
+.PHONY: all serve test list-examples build-all clean lint lint-fix format format-check help
+

README.md

@@ -1,65 +1,68 @@
-This is the experimental beginning of a Python SDK for [Fastly
-Compute](https://www.fastly.com/products/edge-compute).
+# Fastly Compute Python SDK
 
-# Status
+Experimental Python SDK for [Fastly Compute](https://www.fastly.com/products/edge-compute) services.
 
-Currently, this demonstrates…
+## Features
 
-* Building arbitrary pure Python into a component
-* Creating Python bindings from Fastly's WIT files
-* Hosting arbitrary web frameworks by adapting Fastly's API, through those
- bindings, to WSGI
+- **Multiple Framework Support**: Examples with Bottle, Flask, and more
+- **WIT Bindings**: Auto-generated Python bindings from Fastly's WIT files
+- **WSGI Compatibility**: Host any WSGI-compatible web framework
+- **Testing Framework**: Comprehensive viceroy-based integration testing
+- **Type Safety**: Full type hints and IDE support
 
-# Caveats
+## Quick Start
 
-* Any native Python modules need to be compiled against WASI. Few are at the
- moment. However, [Joel has done
- some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
- aren't extensive.
-* Most popular web frameworks we tried [wouldn't work because they depended on
- zlib](https://github.com/bytecodealliance/componentize-py/issues/96) and other
- native-code compression stdlibs which haven't been compiled against WASI yet.
- Moving componentize-py to a new Python may help, as [WASIp1 is now a Tier 2
- supported platform](https://peps.python.org/pep-0011/#tier-2).
+### Build and Run
+```bash
+make serve # Serve default example (Bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
 
-# Install Dependencies
+Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info
 
-1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
-2. Install [Viceroy](https://github.com/fastly/Viceroy). Make sure you have [a
- branch with up-to-date WIT
- files](https://github.com/fastly/Viceroy/tree/sunfishcode/sync-wit) so it can
- run components.
+### Available Examples
 
-# Build and Run
+```bash
+make list-examples # List all examples
+make build-all # Build all examples
+```
 
-1. `make serve`
-2. Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info in a browser.
+### Testing
+```bash
+make test # Run integration tests
+```
 
-You are seeing Bottle, a simple Python web framework, run on a Fastly Compute
-worker!
+## Development
 
-# Testing
+### Code Quality
+```bash
+make format # Format code
+make lint # Run linter
+make lint-fix # Auto-fix linting issues
+```
 
+### Building Examples
 ```bash
-# Install dependencies and run tests
-uv sync --extra dev --extra test
-make test
+make build/my-app.wasm # Build specific example
+make clean # Clean build artifacts
 ```
 
-The tests automatically build the WebAssembly component, start viceroy, and verify all endpoints work correctly with the WIT APIs.
+## Status
 
-# Development
+Currently demonstrates:
+- Building pure Python into WebAssembly components
+- Creating Python bindings from Fastly's WIT files
+- Hosting web frameworks by adapting Fastly's API to WSGI
+- Comprehensive testing with viceroy integration
 
-```bash
-# Format code
-make format
+## Caveats
 
-# Check formatting
-make format-check
+- Any native Python modules need to be compiled against WASI. Few are at the
+ moment. However, [Joel has done
+ some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
+ aren't extensive.
 
-# Run linting
-make lint
+## Prerequisites
 
-# Run linting and apply automatic fixes
-make lint-fix
-```
+1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install [Viceroy](https://github.com/fastly/Viceroy) with component support

examples/README.md

@@ -0,0 +1,73 @@
+# Fastly Compute Python Examples
+
+This directory contains example applications demonstrating different approaches to building Fastly Compute services with Python.
+
+## Available Examples
+
+### `wit-bottle.py`
+- **Framework**: Bottle (lightweight WSGI framework)
+- **Features**: Basic routing, JSON responses, WIT API integration
+- **Use Case**: Simple services, proof-of-concept applications
+
+### `flask-app.py`
+- **Framework**: Flask (popular Python web framework)
+- **Features**: Flask routing, request handling, error handling
+- **Use Case**: More complex applications, familiar Flask patterns
+
+## Building and Running Examples
+
+### Build a Specific Example
+```bash
+make build/flask-app.wasm # Build Flask example
+make build/wit-bottle.wasm # Build Bottle example
+```
+
+### Serve an Example
+```bash
+make serve # Serve default (wit-bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
+
+### Build All Examples
+```bash
+make build-all
+```
+
+### List Available Examples
+```bash
+make list-examples
+```
+
+## Testing Examples
+
+The integration tests use the default example (wit-bottle). To test other examples:
+
+```bash
+# Update the test to use a different example
+EXAMPLE=flask-app make test
+```
+
+## Creating New Examples
+
+1. Create a new `.py` file in this directory
+2. Implement your WSGI application
+3. Include the `serve_wsgi_request` function and `HttpIncoming` class
+4. Build with `make build/your-example.wasm`
+5. Test with `make serve EXAMPLE=your-example`
+
+## Framework Requirements
+
+All examples must:
+- Be WSGI-compatible applications
+- Include the WIT integration boilerplate (`serve_wsgi_request`, `HttpIncoming`)
+- Handle the standard test endpoints for integration tests:
+ - `/hello/<name>` - Returns "Hello {name}!"
+ - `/info` - Returns JSON with service info and WIT data
+ - `/error` - Raises an exception for error testing
+
+## Dependencies
+
+Examples may use different web frameworks, but they all rely on:
+- `wit_world` - Generated WIT bindings
+- `componentize-py` - Python to WebAssembly compilation
+- Framework-specific dependencies (bottle, flask, etc.)

.github/workflows/python-ci.yml

@@ -27,8 +27,6 @@ jobs:
  run: uv sync
  - name: Install viceroy
  run: cargo install --git https://github.com/fastly/Viceroy.git --branch sunfishcode/sync-wit viceroy
- - name: Build WebAssembly component
- run: make app.wasm
  - name: Install dependencies
  run: uv sync --extra dev --extra test
  - name: Check formatting

.gitignore

@@ -5,4 +5,7 @@ uv.lock
 
 /stubs/
 __pycache__
-app.wasm
+
+# Build artifacts
+/build/
+*.wasm

Makefile

@@ -1,18 +1,56 @@
-all: app.wasm
+# Fastly Compute Python SDK
 
+# Configuration
 STUBS_DIR := stubs
+BUILD_DIR := build
+EXAMPLES_DIR := examples
 
-app.wasm: wit/viceroy.wit wit/deps/fastly/compute.wit app.py
-	rm -rf ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy bindings ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy componentize app -o app.wasm
+# Define all available examples (add new ones here)
+EXAMPLES := wit-bottle flask-app
 
-serve: app.wasm
-	viceroy serve app.wasm
+# Default example for serve target
+EXAMPLE ?= wit-bottle
+WASM_FILE := $(BUILD_DIR)/$(EXAMPLE).wasm
 
-test: app.wasm
+# Generate WASM file paths for all examples
+EXAMPLE_WASMS := $(foreach example,$(EXAMPLES),$(BUILD_DIR)/$(example).wasm)
+
+# Default target builds all examples
+all: $(EXAMPLE_WASMS)
+
+# Pattern rule for building any example
+$(BUILD_DIR)/%.wasm: $(EXAMPLES_DIR)/%.py wit/viceroy.wit wit/deps/fastly/compute.wit | $(BUILD_DIR)
+	@echo "Building $* example..."
+	rm -rf $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy bindings $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy componentize $* -p $(EXAMPLES_DIR) -p . -o $@
+
+# Create build directory
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Serve the specified example (default: wit-bottle)
+serve: $(WASM_FILE)
+	@echo "Serving $(EXAMPLE) example on http://127.0.0.1:7676"
+	viceroy serve $(WASM_FILE)
+
+# Test all examples (requires all WASM files to be built)
+test: $(EXAMPLE_WASMS)
 	uv run --extra test pytest
 
+# List available examples
+list-examples:
+	@echo "Available examples:"
+	@for example in $(EXAMPLES); do echo " $$example"; done
+
+# Build all examples (alias for 'all')
+build-all: all
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR) $(STUBS_DIR)
+
+# Development tools
 lint:
 	uv run --extra dev ruff check .
 
@@ -25,4 +63,29 @@ format:
 format-check:
 	uv run --extra dev ruff format --check .
 
-.PHONY: all serve test lint format format-check
+# Help target
+help:
+	@echo "Fastly Compute Python SDK"
+	@echo ""
+	@echo "Targets:"
+	@echo " all Build all examples"
+	@echo " serve [EXAMPLE=name] Serve example (default: $(EXAMPLE))"
+	@echo " test Run integration tests (builds all examples)"
+	@echo " build-all Build all examples (alias for 'all')"
+	@echo " list-examples List available examples"
+	@echo " clean Clean build artifacts"
+	@echo " lint Run linter"
+	@echo " lint-fix Run linter with auto-fix"
+	@echo " format Format code"
+	@echo " format-check Check code formatting"
+	@echo ""
+	@echo "Examples:"
+	@echo " make # Build all examples"
+	@echo " make serve # Serve wit-bottle example"
+	@echo " make serve EXAMPLE=flask-app # Serve flask-app example"
+	@echo " make build/flask-app.wasm # Build specific example"
+	@echo ""
+	@echo "Available examples: $(EXAMPLES)"
+
+.PHONY: all serve test list-examples build-all clean lint lint-fix format format-check help
+

README.md

@@ -1,65 +1,68 @@
-This is the experimental beginning of a Python SDK for [Fastly
-Compute](https://www.fastly.com/products/edge-compute).
+# Fastly Compute Python SDK
 
-# Status
+Experimental Python SDK for [Fastly Compute](https://www.fastly.com/products/edge-compute) services.
 
-Currently, this demonstrates…
+## Features
 
-* Building arbitrary pure Python into a component
-* Creating Python bindings from Fastly's WIT files
-* Hosting arbitrary web frameworks by adapting Fastly's API, through those
- bindings, to WSGI
+- **Multiple Framework Support**: Examples with Bottle, Flask, and more
+- **WIT Bindings**: Auto-generated Python bindings from Fastly's WIT files
+- **WSGI Compatibility**: Host any WSGI-compatible web framework
+- **Testing Framework**: Comprehensive viceroy-based integration testing
+- **Type Safety**: Full type hints and IDE support
 
-# Caveats
+## Quick Start
 
-* Any native Python modules need to be compiled against WASI. Few are at the
- moment. However, [Joel has done
- some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
- aren't extensive.
-* Most popular web frameworks we tried [wouldn't work because they depended on
- zlib](https://github.com/bytecodealliance/componentize-py/issues/96) and other
- native-code compression stdlibs which haven't been compiled against WASI yet.
- Moving componentize-py to a new Python may help, as [WASIp1 is now a Tier 2
- supported platform](https://peps.python.org/pep-0011/#tier-2).
+### Build and Run
+```bash
+make serve # Serve default example (Bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
 
-# Install Dependencies
+Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info
 
-1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
-2. Install [Viceroy](https://github.com/fastly/Viceroy). Make sure you have [a
- branch with up-to-date WIT
- files](https://github.com/fastly/Viceroy/tree/sunfishcode/sync-wit) so it can
- run components.
+### Available Examples
 
-# Build and Run
+```bash
+make list-examples # List all examples
+make build-all # Build all examples
+```
 
-1. `make serve`
-2. Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info in a browser.
+### Testing
+```bash
+make test # Run integration tests
+```
 
-You are seeing Bottle, a simple Python web framework, run on a Fastly Compute
-worker!
+## Development
 
-# Testing
+### Code Quality
+```bash
+make format # Format code
+make lint # Run linter
+make lint-fix # Auto-fix linting issues
+```
 
+### Building Examples
 ```bash
-# Install dependencies and run tests
-uv sync --extra dev --extra test
-make test
+make build/my-app.wasm # Build specific example
+make clean # Clean build artifacts
 ```
 
-The tests automatically build the WebAssembly component, start viceroy, and verify all endpoints work correctly with the WIT APIs.
+## Status
 
-# Development
+Currently demonstrates:
+- Building pure Python into WebAssembly components
+- Creating Python bindings from Fastly's WIT files
+- Hosting web frameworks by adapting Fastly's API to WSGI
+- Comprehensive testing with viceroy integration
 
-```bash
-# Format code
-make format
+## Caveats
 
-# Check formatting
-make format-check
+- Any native Python modules need to be compiled against WASI. Few are at the
+ moment. However, [Joel has done
+ some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
+ aren't extensive.
 
-# Run linting
-make lint
+## Prerequisites
 
-# Run linting and apply automatic fixes
-make lint-fix
-```
+1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install [Viceroy](https://github.com/fastly/Viceroy) with component support

examples/README.md

@@ -0,0 +1,73 @@
+# Fastly Compute Python Examples
+
+This directory contains example applications demonstrating different approaches to building Fastly Compute services with Python.
+
+## Available Examples
+
+### `wit-bottle.py`
+- **Framework**: Bottle (lightweight WSGI framework)
+- **Features**: Basic routing, JSON responses, WIT API integration
+- **Use Case**: Simple services, proof-of-concept applications
+
+### `flask-app.py`
+- **Framework**: Flask (popular Python web framework)
+- **Features**: Flask routing, request handling, error handling
+- **Use Case**: More complex applications, familiar Flask patterns
+
+## Building and Running Examples
+
+### Build a Specific Example
+```bash
+make build/flask-app.wasm # Build Flask example
+make build/wit-bottle.wasm # Build Bottle example
+```
+
+### Serve an Example
+```bash
+make serve # Serve default (wit-bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
+
+### Build All Examples
+```bash
+make build-all
+```
+
+### List Available Examples
+```bash
+make list-examples
+```
+
+## Testing Examples
+
+The integration tests use the default example (wit-bottle). To test other examples:
+
+```bash
+# Update the test to use a different example
+EXAMPLE=flask-app make test
+```
+
+## Creating New Examples
+
+1. Create a new `.py` file in this directory
+2. Implement your WSGI application
+3. Include the `serve_wsgi_request` function and `HttpIncoming` class
+4. Build with `make build/your-example.wasm`
+5. Test with `make serve EXAMPLE=your-example`
+
+## Framework Requirements
+
+All examples must:
+- Be WSGI-compatible applications
+- Include the WIT integration boilerplate (`serve_wsgi_request`, `HttpIncoming`)
+- Handle the standard test endpoints for integration tests:
+ - `/hello/<name>` - Returns "Hello {name}!"
+ - `/info` - Returns JSON with service info and WIT data
+ - `/error` - Raises an exception for error testing
+
+## Dependencies
+
+Examples may use different web frameworks, but they all rely on:
+- `wit_world` - Generated WIT bindings
+- `componentize-py` - Python to WebAssembly compilation
+- Framework-specific dependencies (bottle, flask, etc.)

.github/workflows/python-ci.yml

@@ -27,8 +27,6 @@ jobs:
  run: uv sync
  - name: Install viceroy
  run: cargo install --git https://github.com/fastly/Viceroy.git --branch sunfishcode/sync-wit viceroy
- - name: Build WebAssembly component
- run: make app.wasm
  - name: Install dependencies
  run: uv sync --extra dev --extra test
  - name: Check formatting

.gitignore

@@ -5,4 +5,7 @@ uv.lock
 
 /stubs/
 __pycache__
-app.wasm
+
+# Build artifacts
+/build/
+*.wasm

Makefile

@@ -1,18 +1,56 @@
-all: app.wasm
+# Fastly Compute Python SDK
 
+# Configuration
 STUBS_DIR := stubs
+BUILD_DIR := build
+EXAMPLES_DIR := examples
 
-app.wasm: wit/viceroy.wit wit/deps/fastly/compute.wit app.py
-	rm -rf ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy bindings ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy componentize app -o app.wasm
+# Define all available examples (add new ones here)
+EXAMPLES := wit-bottle flask-app
 
-serve: app.wasm
-	viceroy serve app.wasm
+# Default example for serve target
+EXAMPLE ?= wit-bottle
+WASM_FILE := $(BUILD_DIR)/$(EXAMPLE).wasm
 
-test: app.wasm
+# Generate WASM file paths for all examples
+EXAMPLE_WASMS := $(foreach example,$(EXAMPLES),$(BUILD_DIR)/$(example).wasm)
+
+# Default target builds all examples
+all: $(EXAMPLE_WASMS)
+
+# Pattern rule for building any example
+$(BUILD_DIR)/%.wasm: $(EXAMPLES_DIR)/%.py wit/viceroy.wit wit/deps/fastly/compute.wit | $(BUILD_DIR)
+	@echo "Building $* example..."
+	rm -rf $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy bindings $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy componentize $* -p $(EXAMPLES_DIR) -p . -o $@
+
+# Create build directory
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Serve the specified example (default: wit-bottle)
+serve: $(WASM_FILE)
+	@echo "Serving $(EXAMPLE) example on http://127.0.0.1:7676"
+	viceroy serve $(WASM_FILE)
+
+# Test all examples (requires all WASM files to be built)
+test: $(EXAMPLE_WASMS)
 	uv run --extra test pytest
 
+# List available examples
+list-examples:
+	@echo "Available examples:"
+	@for example in $(EXAMPLES); do echo " $$example"; done
+
+# Build all examples (alias for 'all')
+build-all: all
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR) $(STUBS_DIR)
+
+# Development tools
 lint:
 	uv run --extra dev ruff check .
 
@@ -25,4 +63,29 @@ format:
 format-check:
 	uv run --extra dev ruff format --check .
 
-.PHONY: all serve test lint format format-check
+# Help target
+help:
+	@echo "Fastly Compute Python SDK"
+	@echo ""
+	@echo "Targets:"
+	@echo " all Build all examples"
+	@echo " serve [EXAMPLE=name] Serve example (default: $(EXAMPLE))"
+	@echo " test Run integration tests (builds all examples)"
+	@echo " build-all Build all examples (alias for 'all')"
+	@echo " list-examples List available examples"
+	@echo " clean Clean build artifacts"
+	@echo " lint Run linter"
+	@echo " lint-fix Run linter with auto-fix"
+	@echo " format Format code"
+	@echo " format-check Check code formatting"
+	@echo ""
+	@echo "Examples:"
+	@echo " make # Build all examples"
+	@echo " make serve # Serve wit-bottle example"
+	@echo " make serve EXAMPLE=flask-app # Serve flask-app example"
+	@echo " make build/flask-app.wasm # Build specific example"
+	@echo ""
+	@echo "Available examples: $(EXAMPLES)"
+
+.PHONY: all serve test list-examples build-all clean lint lint-fix format format-check help
+

README.md

@@ -1,65 +1,68 @@
-This is the experimental beginning of a Python SDK for [Fastly
-Compute](https://www.fastly.com/products/edge-compute).
+# Fastly Compute Python SDK
 
-# Status
+Experimental Python SDK for [Fastly Compute](https://www.fastly.com/products/edge-compute) services.
 
-Currently, this demonstrates…
+## Features
 
-* Building arbitrary pure Python into a component
-* Creating Python bindings from Fastly's WIT files
-* Hosting arbitrary web frameworks by adapting Fastly's API, through those
- bindings, to WSGI
+- **Multiple Framework Support**: Examples with Bottle, Flask, and more
+- **WIT Bindings**: Auto-generated Python bindings from Fastly's WIT files
+- **WSGI Compatibility**: Host any WSGI-compatible web framework
+- **Testing Framework**: Comprehensive viceroy-based integration testing
+- **Type Safety**: Full type hints and IDE support
 
-# Caveats
+## Quick Start
 
-* Any native Python modules need to be compiled against WASI. Few are at the
- moment. However, [Joel has done
- some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
- aren't extensive.
-* Most popular web frameworks we tried [wouldn't work because they depended on
- zlib](https://github.com/bytecodealliance/componentize-py/issues/96) and other
- native-code compression stdlibs which haven't been compiled against WASI yet.
- Moving componentize-py to a new Python may help, as [WASIp1 is now a Tier 2
- supported platform](https://peps.python.org/pep-0011/#tier-2).
+### Build and Run
+```bash
+make serve # Serve default example (Bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
 
-# Install Dependencies
+Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info
 
-1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
-2. Install [Viceroy](https://github.com/fastly/Viceroy). Make sure you have [a
- branch with up-to-date WIT
- files](https://github.com/fastly/Viceroy/tree/sunfishcode/sync-wit) so it can
- run components.
+### Available Examples
 
-# Build and Run
+```bash
+make list-examples # List all examples
+make build-all # Build all examples
+```
 
-1. `make serve`
-2. Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info in a browser.
+### Testing
+```bash
+make test # Run integration tests
+```
 
-You are seeing Bottle, a simple Python web framework, run on a Fastly Compute
-worker!
+## Development
 
-# Testing
+### Code Quality
+```bash
+make format # Format code
+make lint # Run linter
+make lint-fix # Auto-fix linting issues
+```
 
+### Building Examples
 ```bash
-# Install dependencies and run tests
-uv sync --extra dev --extra test
-make test
+make build/my-app.wasm # Build specific example
+make clean # Clean build artifacts
 ```
 
-The tests automatically build the WebAssembly component, start viceroy, and verify all endpoints work correctly with the WIT APIs.
+## Status
 
-# Development
+Currently demonstrates:
+- Building pure Python into WebAssembly components
+- Creating Python bindings from Fastly's WIT files
+- Hosting web frameworks by adapting Fastly's API to WSGI
+- Comprehensive testing with viceroy integration
 
-```bash
-# Format code
-make format
+## Caveats
 
-# Check formatting
-make format-check
+- Any native Python modules need to be compiled against WASI. Few are at the
+ moment. However, [Joel has done
+ some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
+ aren't extensive.
 
-# Run linting
-make lint
+## Prerequisites
 
-# Run linting and apply automatic fixes
-make lint-fix
-```
+1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install [Viceroy](https://github.com/fastly/Viceroy) with component support

examples/README.md

@@ -0,0 +1,73 @@
+# Fastly Compute Python Examples
+
+This directory contains example applications demonstrating different approaches to building Fastly Compute services with Python.
+
+## Available Examples
+
+### `wit-bottle.py`
+- **Framework**: Bottle (lightweight WSGI framework)
+- **Features**: Basic routing, JSON responses, WIT API integration
+- **Use Case**: Simple services, proof-of-concept applications
+
+### `flask-app.py`
+- **Framework**: Flask (popular Python web framework)
+- **Features**: Flask routing, request handling, error handling
+- **Use Case**: More complex applications, familiar Flask patterns
+
+## Building and Running Examples
+
+### Build a Specific Example
+```bash
+make build/flask-app.wasm # Build Flask example
+make build/wit-bottle.wasm # Build Bottle example
+```
+
+### Serve an Example
+```bash
+make serve # Serve default (wit-bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
+
+### Build All Examples
+```bash
+make build-all
+```
+
+### List Available Examples
+```bash
+make list-examples
+```
+
+## Testing Examples
+
+The integration tests use the default example (wit-bottle). To test other examples:
+
+```bash
+# Update the test to use a different example
+EXAMPLE=flask-app make test
+```
+
+## Creating New Examples
+
+1. Create a new `.py` file in this directory
+2. Implement your WSGI application
+3. Include the `serve_wsgi_request` function and `HttpIncoming` class
+4. Build with `make build/your-example.wasm`
+5. Test with `make serve EXAMPLE=your-example`
+
+## Framework Requirements
+
+All examples must:
+- Be WSGI-compatible applications
+- Include the WIT integration boilerplate (`serve_wsgi_request`, `HttpIncoming`)
+- Handle the standard test endpoints for integration tests:
+ - `/hello/<name>` - Returns "Hello {name}!"
+ - `/info` - Returns JSON with service info and WIT data
+ - `/error` - Raises an exception for error testing
+
+## Dependencies
+
+Examples may use different web frameworks, but they all rely on:
+- `wit_world` - Generated WIT bindings
+- `componentize-py` - Python to WebAssembly compilation
+- Framework-specific dependencies (bottle, flask, etc.)

.github/workflows/python-ci.yml

@@ -27,8 +27,6 @@ jobs:
  run: uv sync
  - name: Install viceroy
  run: cargo install --git https://github.com/fastly/Viceroy.git --branch sunfishcode/sync-wit viceroy
- - name: Build WebAssembly component
- run: make app.wasm
  - name: Install dependencies
  run: uv sync --extra dev --extra test
  - name: Check formatting

.gitignore

@@ -5,4 +5,7 @@ uv.lock
 
 /stubs/
 __pycache__
-app.wasm
+
+# Build artifacts
+/build/
+*.wasm

Makefile

@@ -1,18 +1,56 @@
-all: app.wasm
+# Fastly Compute Python SDK
 
+# Configuration
 STUBS_DIR := stubs
+BUILD_DIR := build
+EXAMPLES_DIR := examples
 
-app.wasm: wit/viceroy.wit wit/deps/fastly/compute.wit app.py
-	rm -rf ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy bindings ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy componentize app -o app.wasm
+# Define all available examples (add new ones here)
+EXAMPLES := wit-bottle flask-app
 
-serve: app.wasm
-	viceroy serve app.wasm
+# Default example for serve target
+EXAMPLE ?= wit-bottle
+WASM_FILE := $(BUILD_DIR)/$(EXAMPLE).wasm
 
-test: app.wasm
+# Generate WASM file paths for all examples
+EXAMPLE_WASMS := $(foreach example,$(EXAMPLES),$(BUILD_DIR)/$(example).wasm)
+
+# Default target builds all examples
+all: $(EXAMPLE_WASMS)
+
+# Pattern rule for building any example
+$(BUILD_DIR)/%.wasm: $(EXAMPLES_DIR)/%.py wit/viceroy.wit wit/deps/fastly/compute.wit | $(BUILD_DIR)
+	@echo "Building $* example..."
+	rm -rf $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy bindings $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy componentize $* -p $(EXAMPLES_DIR) -p . -o $@
+
+# Create build directory
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Serve the specified example (default: wit-bottle)
+serve: $(WASM_FILE)
+	@echo "Serving $(EXAMPLE) example on http://127.0.0.1:7676"
+	viceroy serve $(WASM_FILE)
+
+# Test all examples (requires all WASM files to be built)
+test: $(EXAMPLE_WASMS)
 	uv run --extra test pytest
 
+# List available examples
+list-examples:
+	@echo "Available examples:"
+	@for example in $(EXAMPLES); do echo " $$example"; done
+
+# Build all examples (alias for 'all')
+build-all: all
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR) $(STUBS_DIR)
+
+# Development tools
 lint:
 	uv run --extra dev ruff check .
 
@@ -25,4 +63,29 @@ format:
 format-check:
 	uv run --extra dev ruff format --check .
 
-.PHONY: all serve test lint format format-check
+# Help target
+help:
+	@echo "Fastly Compute Python SDK"
+	@echo ""
+	@echo "Targets:"
+	@echo " all Build all examples"
+	@echo " serve [EXAMPLE=name] Serve example (default: $(EXAMPLE))"
+	@echo " test Run integration tests (builds all examples)"
+	@echo " build-all Build all examples (alias for 'all')"
+	@echo " list-examples List available examples"
+	@echo " clean Clean build artifacts"
+	@echo " lint Run linter"
+	@echo " lint-fix Run linter with auto-fix"
+	@echo " format Format code"
+	@echo " format-check Check code formatting"
+	@echo ""
+	@echo "Examples:"
+	@echo " make # Build all examples"
+	@echo " make serve # Serve wit-bottle example"
+	@echo " make serve EXAMPLE=flask-app # Serve flask-app example"
+	@echo " make build/flask-app.wasm # Build specific example"
+	@echo ""
+	@echo "Available examples: $(EXAMPLES)"
+
+.PHONY: all serve test list-examples build-all clean lint lint-fix format format-check help
+

README.md

@@ -1,65 +1,68 @@
-This is the experimental beginning of a Python SDK for [Fastly
-Compute](https://www.fastly.com/products/edge-compute).
+# Fastly Compute Python SDK
 
-# Status
+Experimental Python SDK for [Fastly Compute](https://www.fastly.com/products/edge-compute) services.
 
-Currently, this demonstrates…
+## Features
 
-* Building arbitrary pure Python into a component
-* Creating Python bindings from Fastly's WIT files
-* Hosting arbitrary web frameworks by adapting Fastly's API, through those
- bindings, to WSGI
+- **Multiple Framework Support**: Examples with Bottle, Flask, and more
+- **WIT Bindings**: Auto-generated Python bindings from Fastly's WIT files
+- **WSGI Compatibility**: Host any WSGI-compatible web framework
+- **Testing Framework**: Comprehensive viceroy-based integration testing
+- **Type Safety**: Full type hints and IDE support
 
-# Caveats
+## Quick Start
 
-* Any native Python modules need to be compiled against WASI. Few are at the
- moment. However, [Joel has done
- some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
- aren't extensive.
-* Most popular web frameworks we tried [wouldn't work because they depended on
- zlib](https://github.com/bytecodealliance/componentize-py/issues/96) and other
- native-code compression stdlibs which haven't been compiled against WASI yet.
- Moving componentize-py to a new Python may help, as [WASIp1 is now a Tier 2
- supported platform](https://peps.python.org/pep-0011/#tier-2).
+### Build and Run
+```bash
+make serve # Serve default example (Bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
 
-# Install Dependencies
+Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info
 
-1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
-2. Install [Viceroy](https://github.com/fastly/Viceroy). Make sure you have [a
- branch with up-to-date WIT
- files](https://github.com/fastly/Viceroy/tree/sunfishcode/sync-wit) so it can
- run components.
+### Available Examples
 
-# Build and Run
+```bash
+make list-examples # List all examples
+make build-all # Build all examples
+```
 
-1. `make serve`
-2. Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info in a browser.
+### Testing
+```bash
+make test # Run integration tests
+```
 
-You are seeing Bottle, a simple Python web framework, run on a Fastly Compute
-worker!
+## Development
 
-# Testing
+### Code Quality
+```bash
+make format # Format code
+make lint # Run linter
+make lint-fix # Auto-fix linting issues
+```
 
+### Building Examples
 ```bash
-# Install dependencies and run tests
-uv sync --extra dev --extra test
-make test
+make build/my-app.wasm # Build specific example
+make clean # Clean build artifacts
 ```
 
-The tests automatically build the WebAssembly component, start viceroy, and verify all endpoints work correctly with the WIT APIs.
+## Status
 
-# Development
+Currently demonstrates:
+- Building pure Python into WebAssembly components
+- Creating Python bindings from Fastly's WIT files
+- Hosting web frameworks by adapting Fastly's API to WSGI
+- Comprehensive testing with viceroy integration
 
-```bash
-# Format code
-make format
+## Caveats
 
-# Check formatting
-make format-check
+- Any native Python modules need to be compiled against WASI. Few are at the
+ moment. However, [Joel has done
+ some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
+ aren't extensive.
 
-# Run linting
-make lint
+## Prerequisites
 
-# Run linting and apply automatic fixes
-make lint-fix
-```
+1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install [Viceroy](https://github.com/fastly/Viceroy) with component support

examples/README.md

@@ -0,0 +1,73 @@
+# Fastly Compute Python Examples
+
+This directory contains example applications demonstrating different approaches to building Fastly Compute services with Python.
+
+## Available Examples
+
+### `wit-bottle.py`
+- **Framework**: Bottle (lightweight WSGI framework)
+- **Features**: Basic routing, JSON responses, WIT API integration
+- **Use Case**: Simple services, proof-of-concept applications
+
+### `flask-app.py`
+- **Framework**: Flask (popular Python web framework)
+- **Features**: Flask routing, request handling, error handling
+- **Use Case**: More complex applications, familiar Flask patterns
+
+## Building and Running Examples
+
+### Build a Specific Example
+```bash
+make build/flask-app.wasm # Build Flask example
+make build/wit-bottle.wasm # Build Bottle example
+```
+
+### Serve an Example
+```bash
+make serve # Serve default (wit-bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
+
+### Build All Examples
+```bash
+make build-all
+```
+
+### List Available Examples
+```bash
+make list-examples
+```
+
+## Testing Examples
+
+The integration tests use the default example (wit-bottle). To test other examples:
+
+```bash
+# Update the test to use a different example
+EXAMPLE=flask-app make test
+```
+
+## Creating New Examples
+
+1. Create a new `.py` file in this directory
+2. Implement your WSGI application
+3. Include the `serve_wsgi_request` function and `HttpIncoming` class
+4. Build with `make build/your-example.wasm`
+5. Test with `make serve EXAMPLE=your-example`
+
+## Framework Requirements
+
+All examples must:
+- Be WSGI-compatible applications
+- Include the WIT integration boilerplate (`serve_wsgi_request`, `HttpIncoming`)
+- Handle the standard test endpoints for integration tests:
+ - `/hello/<name>` - Returns "Hello {name}!"
+ - `/info` - Returns JSON with service info and WIT data
+ - `/error` - Raises an exception for error testing
+
+## Dependencies
+
+Examples may use different web frameworks, but they all rely on:
+- `wit_world` - Generated WIT bindings
+- `componentize-py` - Python to WebAssembly compilation
+- Framework-specific dependencies (bottle, flask, etc.)

.github/workflows/python-ci.yml

@@ -27,8 +27,6 @@ jobs:
  run: uv sync
  - name: Install viceroy
  run: cargo install --git https://github.com/fastly/Viceroy.git --branch sunfishcode/sync-wit viceroy
- - name: Build WebAssembly component
- run: make app.wasm
  - name: Install dependencies
  run: uv sync --extra dev --extra test
  - name: Check formatting

.gitignore

@@ -5,4 +5,7 @@ uv.lock
 
 /stubs/
 __pycache__
-app.wasm
+
+# Build artifacts
+/build/
+*.wasm

Makefile

@@ -1,18 +1,56 @@
-all: app.wasm
+# Fastly Compute Python SDK
 
+# Configuration
 STUBS_DIR := stubs
+BUILD_DIR := build
+EXAMPLES_DIR := examples
 
-app.wasm: wit/viceroy.wit wit/deps/fastly/compute.wit app.py
-	rm -rf ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy bindings ${STUBS_DIR}
-	uv run componentize-py -d wit -w viceroy componentize app -o app.wasm
+# Define all available examples (add new ones here)
+EXAMPLES := wit-bottle flask-app
 
-serve: app.wasm
-	viceroy serve app.wasm
+# Default example for serve target
+EXAMPLE ?= wit-bottle
+WASM_FILE := $(BUILD_DIR)/$(EXAMPLE).wasm
 
-test: app.wasm
+# Generate WASM file paths for all examples
+EXAMPLE_WASMS := $(foreach example,$(EXAMPLES),$(BUILD_DIR)/$(example).wasm)
+
+# Default target builds all examples
+all: $(EXAMPLE_WASMS)
+
+# Pattern rule for building any example
+$(BUILD_DIR)/%.wasm: $(EXAMPLES_DIR)/%.py wit/viceroy.wit wit/deps/fastly/compute.wit | $(BUILD_DIR)
+	@echo "Building $* example..."
+	rm -rf $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy bindings $(STUBS_DIR)
+	uv run componentize-py -d wit -w viceroy componentize $* -p $(EXAMPLES_DIR) -p . -o $@
+
+# Create build directory
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Serve the specified example (default: wit-bottle)
+serve: $(WASM_FILE)
+	@echo "Serving $(EXAMPLE) example on http://127.0.0.1:7676"
+	viceroy serve $(WASM_FILE)
+
+# Test all examples (requires all WASM files to be built)
+test: $(EXAMPLE_WASMS)
 	uv run --extra test pytest
 
+# List available examples
+list-examples:
+	@echo "Available examples:"
+	@for example in $(EXAMPLES); do echo " $$example"; done
+
+# Build all examples (alias for 'all')
+build-all: all
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR) $(STUBS_DIR)
+
+# Development tools
 lint:
 	uv run --extra dev ruff check .
 
@@ -25,4 +63,29 @@ format:
 format-check:
 	uv run --extra dev ruff format --check .
 
-.PHONY: all serve test lint format format-check
+# Help target
+help:
+	@echo "Fastly Compute Python SDK"
+	@echo ""
+	@echo "Targets:"
+	@echo " all Build all examples"
+	@echo " serve [EXAMPLE=name] Serve example (default: $(EXAMPLE))"
+	@echo " test Run integration tests (builds all examples)"
+	@echo " build-all Build all examples (alias for 'all')"
+	@echo " list-examples List available examples"
+	@echo " clean Clean build artifacts"
+	@echo " lint Run linter"
+	@echo " lint-fix Run linter with auto-fix"
+	@echo " format Format code"
+	@echo " format-check Check code formatting"
+	@echo ""
+	@echo "Examples:"
+	@echo " make # Build all examples"
+	@echo " make serve # Serve wit-bottle example"
+	@echo " make serve EXAMPLE=flask-app # Serve flask-app example"
+	@echo " make build/flask-app.wasm # Build specific example"
+	@echo ""
+	@echo "Available examples: $(EXAMPLES)"
+
+.PHONY: all serve test list-examples build-all clean lint lint-fix format format-check help
+

README.md

@@ -1,65 +1,68 @@
-This is the experimental beginning of a Python SDK for [Fastly
-Compute](https://www.fastly.com/products/edge-compute).
+# Fastly Compute Python SDK
 
-# Status
+Experimental Python SDK for [Fastly Compute](https://www.fastly.com/products/edge-compute) services.
 
-Currently, this demonstrates…
+## Features
 
-* Building arbitrary pure Python into a component
-* Creating Python bindings from Fastly's WIT files
-* Hosting arbitrary web frameworks by adapting Fastly's API, through those
- bindings, to WSGI
+- **Multiple Framework Support**: Examples with Bottle, Flask, and more
+- **WIT Bindings**: Auto-generated Python bindings from Fastly's WIT files
+- **WSGI Compatibility**: Host any WSGI-compatible web framework
+- **Testing Framework**: Comprehensive viceroy-based integration testing
+- **Type Safety**: Full type hints and IDE support
 
-# Caveats
+## Quick Start
 
-* Any native Python modules need to be compiled against WASI. Few are at the
- moment. However, [Joel has done
- some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
- aren't extensive.
-* Most popular web frameworks we tried [wouldn't work because they depended on
- zlib](https://github.com/bytecodealliance/componentize-py/issues/96) and other
- native-code compression stdlibs which haven't been compiled against WASI yet.
- Moving componentize-py to a new Python may help, as [WASIp1 is now a Tier 2
- supported platform](https://peps.python.org/pep-0011/#tier-2).
+### Build and Run
+```bash
+make serve # Serve default example (Bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
 
-# Install Dependencies
+Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info
 
-1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
-2. Install [Viceroy](https://github.com/fastly/Viceroy). Make sure you have [a
- branch with up-to-date WIT
- files](https://github.com/fastly/Viceroy/tree/sunfishcode/sync-wit) so it can
- run components.
+### Available Examples
 
-# Build and Run
+```bash
+make list-examples # List all examples
+make build-all # Build all examples
+```
 
-1. `make serve`
-2. Visit http://127.0.0.1:7676/hello/world or http://127.0.0.1:7676/info in a browser.
+### Testing
+```bash
+make test # Run integration tests
+```
 
-You are seeing Bottle, a simple Python web framework, run on a Fastly Compute
-worker!
+## Development
 
-# Testing
+### Code Quality
+```bash
+make format # Format code
+make lint # Run linter
+make lint-fix # Auto-fix linting issues
+```
 
+### Building Examples
 ```bash
-# Install dependencies and run tests
-uv sync --extra dev --extra test
-make test
+make build/my-app.wasm # Build specific example
+make clean # Clean build artifacts
 ```
 
-The tests automatically build the WebAssembly component, start viceroy, and verify all endpoints work correctly with the WIT APIs.
+## Status
 
-# Development
+Currently demonstrates:
+- Building pure Python into WebAssembly components
+- Creating Python bindings from Fastly's WIT files
+- Hosting web frameworks by adapting Fastly's API to WSGI
+- Comprehensive testing with viceroy integration
 
-```bash
-# Format code
-make format
+## Caveats
 
-# Check formatting
-make format-check
+- Any native Python modules need to be compiled against WASI. Few are at the
+ moment. However, [Joel has done
+ some](https://github.com/dicej/wasi-wheels/releases/), and the changes needed
+ aren't extensive.
 
-# Run linting
-make lint
+## Prerequisites
 
-# Run linting and apply automatic fixes
-make lint-fix
-```
+1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/)
+2. Install [Viceroy](https://github.com/fastly/Viceroy) with component support

examples/README.md

@@ -0,0 +1,73 @@
+# Fastly Compute Python Examples
+
+This directory contains example applications demonstrating different approaches to building Fastly Compute services with Python.
+
+## Available Examples
+
+### `wit-bottle.py`
+- **Framework**: Bottle (lightweight WSGI framework)
+- **Features**: Basic routing, JSON responses, WIT API integration
+- **Use Case**: Simple services, proof-of-concept applications
+
+### `flask-app.py`
+- **Framework**: Flask (popular Python web framework)
+- **Features**: Flask routing, request handling, error handling
+- **Use Case**: More complex applications, familiar Flask patterns
+
+## Building and Running Examples
+
+### Build a Specific Example
+```bash
+make build/flask-app.wasm # Build Flask example
+make build/wit-bottle.wasm # Build Bottle example
+```
+
+### Serve an Example
+```bash
+make serve # Serve default (wit-bottle)
+make serve EXAMPLE=flask-app # Serve Flask example
+```
+
+### Build All Examples
+```bash
+make build-all
+```
+
+### List Available Examples
+```bash
+make list-examples
+```
+
+## Testing Examples
+
+The integration tests use the default example (wit-bottle). To test other examples:
+
+```bash
+# Update the test to use a different example
+EXAMPLE=flask-app make test
+```
+
+## Creating New Examples
+
+1. Create a new `.py` file in this directory
+2. Implement your WSGI application
+3. Include the `serve_wsgi_request` function and `HttpIncoming` class
+4. Build with `make build/your-example.wasm`
+5. Test with `make serve EXAMPLE=your-example`
+
+## Framework Requirements
+
+All examples must:
+- Be WSGI-compatible applications
+- Include the WIT integration boilerplate (`serve_wsgi_request`, `HttpIncoming`)
+- Handle the standard test endpoints for integration tests:
+ - `/hello/<name>` - Returns "Hello {name}!"
+ - `/info` - Returns JSON with service info and WIT data
+ - `/error` - Raises an exception for error testing
+
+## Dependencies
+
+Examples may use different web frameworks, but they all rely on:
+- `wit_world` - Generated WIT bindings
+- `componentize-py` - Python to WebAssembly compilation
+- Framework-specific dependencies (bottle, flask, etc.)