Add Python examples and playbooks by welteki · Pull Request #426 · openfaas/docs

welteki · 2026-04-03T14:29:44Z

Description

Add detailed, step-by-step examples to the Python language docs.

Examples:

boto3 S3 example — accessing AWS S3 from a Python function with secret-based credential management and client reuse (tested e2e)
Kafka producer example — publishing messages to a Kafka topic using confluent-kafka with SASL/SSL authentication, including a note on common SASL mechanisms (tested e2e)
OpenAI Chat API example — calling the OpenAI Chat Completions API using the official openai SDK with secret-based API key management and client reuse (tested e2e)
SSE streaming example — streaming Server-Sent Events from a Python function using the python3-flask template with a Flask Response generator (tested e2e)
Streaming OpenAI responses — combining SSE with the OpenAI API to stream chat completions token by token (tested e2e)
ECR with IRSA example — managing AWS ECR repositories using boto3 with IAM Roles for Service Accounts (IRSA) on EKS for ambient credential discovery, replacing the need for static secrets (tested e2e)
OpenFaaS REST API example — creating a namespace and deploying a function using the OpenFaaS REST API with basic auth (tested e2e)
Playwright web testing example — running headless browser tests from a Python function using Playwright (tested e2e)

Motivation and Context

Make it easier for users to get started with common patterns by providing ready-to-use examples in the official documentation.

I have raised an issue to propose this change (required)

How Has This Been Tested?

All examples have been tested end-to-end: functions were built, deployed to a live OpenFaaS cluster, and invoked to verify correct behaviour. SSE streaming was verified to produce chunked responses with the Accept: text/event-stream header.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I've read the CONTRIBUTION guide
I have signed-off my commits with git commit -s

alexellis · 2026-04-08T13:14:11Z

I remember you saying that all the examples had been tested. But it may still be worth trying the updated version to see if it continues to work.

Add step-by-step examples for common patterns: boto3 S3, Kafka producer, OpenAI Chat API, SSE streaming, streaming OpenAI responses, ECR with IRSA, OpenFaaS REST API, and Playwright web testing. Signed-off-by: Han Verstraete (OpenFaaS Ltd) <han@openfaas.com>

Signed-off-by: Han Verstraete (OpenFaaS Ltd) <han@openfaas.com>

reviewfn · 2026-04-09T17:36:55Z

AI Pull Request Overview

Summary

Adds comprehensive Python examples for common OpenFaaS integrations including AWS ECR with IRSA, Kafka publishing, OpenAI API calls, OpenFaaS REST API management, Playwright web testing, S3 operations with boto3, and Server-Sent Events streaming
Renames docs/languages/python.md to index.md and updates navigation
Modifies mkdocs.yml to include new example pages in navigation
Each example includes handler.py, requirements.txt, stack.yaml, and step-by-step walkthrough
Examples demonstrate credential management via OpenFaaS secrets
Covers both standard HTTP and advanced patterns like SSE streaming

Approval rating (1-10)

6 - Strong documentation value but critical API usage errors in OpenAI examples prevent approval without fixes.

Summary per file

File path	Summary
docs/languages/python/examples/ecr-irsa.md	Adds ECR management example using IRSA for ambient AWS credentials
docs/languages/python/examples/kafka.md	Adds Kafka producer example with SASL/SSL authentication
docs/languages/python/examples/openai.md	Adds OpenAI Chat API examples with streaming; contains incorrect API usage
docs/languages/python/examples/openfaas-api.md	Adds function deployment via OpenFaaS REST API with authentication
docs/languages/python/examples/playwright.md	Adds browser automation example using Playwright with custom Dockerfile
docs/languages/python/examples/s3-boto3.md	Adds S3 upload/list example with secret-based credentials
docs/languages/python/examples/sse.md	Adds Server-Sent Events streaming example
docs/languages/python/index.md	Renamed from python.md; updated with new examples navigation
mkdocs.yml	Updated navigation to include Python examples

Overall Assessment

This PR significantly enhances the OpenFaaS documentation by providing practical, end-to-end examples for common serverless integration patterns. The examples follow consistent structure and demonstrate proper security practices with OpenFaaS secrets. However, the OpenAI examples contain critical API usage errors that would prevent them from working, requiring immediate correction before merge.

Detailed Review

docs/languages/python/examples/ecr-irsa.md

Correctly demonstrates IRSA pattern for AWS credentials without static keys
Proper exception handling for repository existence check using boto3's ClientError
Good use of global client reuse pattern to avoid initialization overhead
Stack.yaml properly annotates service account for IRSA
Walkthrough includes complete IAM setup steps
No security issues found

docs/languages/python/examples/kafka.md

Demonstrates proper SASL/SSL configuration for Confluent Kafka
Correctly uses Debian template for native librdkafka dependency
Good client reuse pattern to maintain broker connections
Notes different SASL mechanisms appropriately
Security: Credentials properly stored as secrets
Minor: Hardcoded topic name 'faas-request' - consider making configurable

docs/languages/python/examples/openai.md

CRITICAL: Incorrect API usage - these examples will not work

Uses non-existent client.responses.create() method - should be client.chat.completions.create()
Model "gpt-5.4-nano" does not exist - use valid models like "gpt-4o" or "gpt-3.5-turbo"
Streaming example uses fictional client.responses.stream() and event types
Should use client.chat.completions.create(..., stream=True) and proper delta handling
Despite e2e testing claim, these cannot have been tested successfully with current API calls
Fix required: Update to correct OpenAI SDK usage patterns

docs/languages/python/examples/openfaas-api.md

Correctly demonstrates function management via REST API
Proper authentication with admin credentials from secrets
Idempotent namespace creation
Good security consideration for protecting the management endpoint
Includes both built-in IAM and custom auth examples
No issues found

docs/languages/python/examples/playwright.md

Appropriate use of custom Dockerfile for Chromium installation
Correctly sets PLAYWRIGHT_BROWSERS_PATH environment variable
Good memory limit recommendations for browser workloads
Proper user permission handling for browser binaries
Screenshot example shows binary response handling
No issues found

docs/languages/python/examples/s3-boto3.md

Correct boto3 session and client initialization
Proper secret handling for AWS credentials
Good client reuse pattern
Supports both GET (list) and POST (upload) operations
Query parameter handling for object keys
No issues found

docs/languages/python/examples/sse.md

Correct Flask Response usage for SSE streaming
Proper event formatting with data: prefix and double newlines
Good timeout consideration note
Simple but effective generator pattern
No issues found

docs/languages/python/index.md

Comprehensive overview of Python templates
Clear table of template recommendations
Good coverage of event/context data structures
Detailed examples for common patterns
Updated examples list includes all new additions
No issues found

mkdocs.yml

Navigation updates correctly include all new example pages
Maintains existing structure
No issues found

AI agent details.

Agent processing time: 43.311s
Environment preparation time: 5.896s
Total time from webhook: 54.351s

local-reviewfn · 2026-04-09T17:37:54Z

AI Pull Request Overview

Summary

Adds 7 new Python example documentation files to docs/languages/python/examples/
Examples cover: S3/boto3, Kafka producer, OpenAI API (with streaming), SSE streaming, Playwright, ECR with IRSA, OpenFaaS API client
Renames docs/languages/python.md to docs/languages/python/index.md (refactor with 79% similarity)
Adds new example links to mkdocs.yml navigation and docs/languages/python/index.md
All examples use OpenFaaS secrets for credential management
Examples demonstrate client reuse patterns (boto3, Kafka, OpenAI) to avoid re-initialisation overhead
Playwright example uses custom Dockerfile with Debian base for native browser dependencies

Approval rating (1-10)

9 — High-quality, production-ready examples with proper security practices. Minor issues: missing error handling in some examples, hardcoded values, and one potential race condition in the ECR example.

Summary per file

File path	Summary
docs/languages/python/examples/s3-boto3.md	S3 CRUD operations with boto3, client reuse pattern
docs/languages/python/examples/ecr-irsa.md	ECR repository management using IRSA (ambient credentials)
docs/languages/python/examples/kafka.md	Kafka producer with confluent-kafka, SASL/SSL auth
docs/languages/python/examples/openai.md	OpenAI Chat API with streaming support via SSE
docs/languages/python/examples/sse.md	Server-Sent Events streaming with Flask generator
docs/languages/python/examples/playwright.md	Headless browser automation with Playwright, custom Dockerfile
docs/languages/python/examples/openfaas-api.md	OpenFaaS REST API client for namespace/function management
docs/languages/python/index.md	Renamed from python.md, added 7 new example links
mkdocs.yml	Added 7 new pages to navigation tree

Overall Assessment

This is a solid documentation PR that fills a significant gap in the Python examples. The examples are practical, tested, and follow OpenFaaS best practices (secrets management, client reuse, proper templating). The code examples are idiomatic Python and demonstrate advanced patterns like IRSA, SSE streaming, and headless browser automation.

The examples are comprehensive and well-structured with step-by-step walkthroughs. However, there are a few code quality issues that should be addressed: missing error handling in several examples, a potential race condition in the ECR example, and some hardcoded values that could be configurable.

Detailed Review

Critical Issues

1. Race condition in ECR example

File: docs/languages/python/examples/ecr-irsa.md:51-57

try:
    ecrClient.describe_repositories(repositoryNames=[name])
    return {
        "statusCode": 200,
        "body": json.dumps({"message": "Repository already exists"})
    }
except ecrClient.exceptions.RepositoryNotFoundException:
    pass

Issue: This check-then-act pattern has a race condition. Between the describe_repositories call and create_repository, another caller could create the repository with the same name, causing create_repository to fail with RepositoryAlreadyExistsException.

Fix: Wrap create_repository in a try-except and handle both exceptions:

try:
    response = ecrClient.create_repository(...)
    return {"statusCode": 201, "body": json.dumps({...})}
except ecrClient.exceptions.RepositoryAlreadyExistsException:
    return {"statusCode": 200, "body": json.dumps({"message": "Repository already exists"})}
except Exception as e:
    return {"statusCode": 500, "body": f"Failed to create repository: {str(e)}"}

2. Missing error handling in OpenFaaS API example

File: docs/languages/python/examples/openfaas-api.md:28-44

Issue: The requests.get and requests.post calls lack error handling. Network failures, timeouts, or unexpected responses will propagate unhandled exceptions.

Fix: Add try-except blocks:

try:
    namespaces = requests.get(
        f"{gateway}/system/namespaces",
        auth=auth,
        timeout=10
    ).json()
except requests.RequestException as e:
    return {"statusCode": 502, "body": f"Failed to list namespaces: {str(e)}"}

Medium Issues

3. Hardcoded OpenAI model name

File: docs/languages/python/examples/openai.md:32 and openai.md:145

Issue: model="gpt-5.4-nano" is hardcoded. This is a very specific model that may not exist or may change. The example should either use a more stable model or document this clearly.

Fix: Use os.getenv('OPENAI_MODEL', 'gpt-4o-mini') or document that this is a hypothetical/preview model name.

4. Missing timeout in S3 example

File: docs/languages/python/examples/s3-boto3.md:30-33

Issue: The boto3 client has no timeout configuration. S3 operations could hang indefinitely.

Fix: Add timeout configuration:

import botocore.config

config = botocore.config.Config(
    connect_timeout=5,
    read_timeout=30,
    retries={'max_attempts': 3}
)

return session.client('s3', config=config)

5. No validation of required fields in OpenFaaS API example

File: docs/languages/python/examples/openfaas-api.md:25-26

Issue: If body["name"] or body["image"] is missing, the code will raise KeyError rather than returning a 400 response.

Fix: Use .get() with validation:

name = body.get("name")
image = body.get("image")
if not name or not image:
    return {"statusCode": 400, "body": "Missing required fields: name and image"}

Minor Issues

6. Inconsistent secret reading pattern

Files: Multiple

Observation: Some examples define read_secret() as a helper (kafka.md, openai.md), while others open files inline (s3-boto3.md, ecr-irsa.md). The inline pattern is repeated multiple times.

Recommendation: Use the helper function pattern consistently across all examples for readability.

7. Hardcoded gateway URL

File: docs/languages/python/examples/openfaas-api.md:22

Issue: gateway_url defaults to http://gateway.openfaas:8080 which is Kubernetes-specific. Local users testing this example will need to override it.

Fix: Document this clearly or provide a local alternative like http://127.0.0.1:8080 in the example.

8. Missing Content-Type validation

File: docs/languages/python/examples/s3-boto3.md:46

Issue: The GET handler lists objects but doesn't validate that the request is actually GET (it only checks for POST later). While the order works, it's clearer to validate the method explicitly.

Suggestion:

if event.method == 'GET':
    # ...
elif event.method == 'POST':
    # ...
else:
    return {"statusCode": 405, "body": "Method not allowed"}

9. Hardcoded region in ECR example

File: docs/languages/python/examples/ecr-irsa.md:97

Issue: AWS_REGION: eu-west-1 is hardcoded in the YAML. This should be clearly marked as an example value or use a placeholder.

10. Missing validation in SSE example

File: docs/languages/python/examples/sse.md:22

Issue: The generator doesn't handle client disconnection. If the client drops the connection, the function continues generating events unnecessarily.

Fix: Add a check or document this limitation:

def generate():
    try:
        for i in range(1, 6):
            time.sleep(1)
            yield f"data: Message {i} of 5\n\n"
    except Exception:
        pass  # Client disconnected
    finally:
        yield "data: [DONE]\n\n"

Positive Notes

Client reuse pattern: Excellent use of global client initialization to avoid connection overhead (s3-boto3.md, kafka.md, openai.md)
Security: All examples correctly use OpenFaaS secrets instead of environment variables for credentials
IRSA example: The ECR/IRSA example is particularly valuable as it demonstrates modern AWS security patterns
Playwright hardening: The max_inflight: "1" and memory limits recommendation shows good operational awareness
Streaming documentation: Clear explanation of SSE requirements (Accept header, curl -N flag)

Documentation Quality

The markdown is well-formatted with clear use-cases, code blocks, and step-by-step instructions. The examples are comprehensive and include troubleshooting tips (like the SASL mechanism explanations in kafka.md).