From e645e637c1a0039af2fcc3409c00477eded3d1af Mon Sep 17 00:00:00 2001 From: Leandro Damascena Date: Sun, 1 Nov 2026 10:11:08 +0000 Subject: [PATCH] docs: refresh the README and add Circuit Breaker and Metadata to the feature table --- README.md | 101 +++++++++++++++++++++++++++++--------------------- docs/index.md | 2 + 2 files changed, 61 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index f8298a6bea1..d746abcc62a 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,72 @@ # Powertools for AWS Lambda (Python) -[![Build](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/quality_check.yml/badge.svg)](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/python_build.yml) +[![Build](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/quality_check.yml/badge.svg)](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/quality_check.yml) [![codecov.io](https://codecov.io/github/aws-powertools/powertools-lambda-python/branch/develop/graphs/badge.svg)](https://app.codecov.io/gh/aws-powertools/powertools-lambda-python) ![PythonSupport](https://img.shields.io/static/v1?label=python&message=%203.10|%203.11|%203.12|%203.13|%203.14&color=blue?style=flat-square&logo=python) ![PyPI version](https://badge.fury.io/py/aws-lambda-powertools.svg) ![PyPi monthly downloads](https://img.shields.io/pypi/dm/aws-lambda-powertools) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/aws-powertools/powertools-lambda-python/badge)](https://scorecard.dev/viewer/?uri=github.com/aws-powertools/powertools-lambda-python) [![Discord](https://img.shields.io/badge/Discord-Join_Community-7289da.svg)](https://discord.gg/B8zZKbbyET) -Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverless [best practices and increase developer velocity](https://docs.powertools.aws.dev/lambda/python/latest/#features). +Powertools for AWS Lambda (Python) is a developer toolkit for AWS Lambda: structured logging, tracing, metrics, event handlers for API Gateway, AppSync and Bedrock Agents, idempotency, batch processing, parameters, validation, and more. Each utility is independent, follows the Lambda execution model, and is designed to add as little as possible to your cold start. -Also available in [Java](https://github.com/aws-powertools/powertools-lambda-java), [TypeScript](https://github.com/aws-powertools/powertools-lambda-typescript), and [.NET](https://github.com/aws-powertools/powertools-lambda-dotnet). +Also available in [TypeScript](https://github.com/aws-powertools/powertools-lambda-typescript), [Java](https://github.com/aws-powertools/powertools-lambda-java), and [.NET](https://github.com/aws-powertools/powertools-lambda-dotnet). -[οΏ½ Doccumentation](https://docs.powertools.aws.dev/lambda/python/) | [🐍 PyPi](https://pypi.org/project/aws-lambda-powertools/) | [πŸ—ΊοΈ Roadmap](https://docs.powertools.aws.dev/lambda/python/latest/roadmap/) | [πŸ“° Blog](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-lambda-powertools/) +[πŸ“œ Documentation](https://docs.powertools.aws.dev/lambda/python/) | [🐍 PyPI](https://pypi.org/project/aws-lambda-powertools/) | [πŸŽ“ Workshop](https://s12d.com/powertools-for-aws-lambda-workshop) | [πŸ—ΊοΈ Roadmap](https://docs.powertools.aws.dev/lambda/python/latest/roadmap/) | [πŸ“ Changelog](https://docs.powertools.aws.dev/lambda/python/latest/changelog/) ![hero-image](https://user-images.githubusercontent.com/3340292/198254617-d0fdb672-86a6-4988-8a40-adf437135e0a.png) +## Installation + +```bash +pip install aws-lambda-powertools +# or +uv add aws-lambda-powertools +``` + +Or use the [public Lambda layer](https://docs.powertools.aws.dev/lambda/python/latest/getting-started/install/#lambda-layer), published for every supported Python version on `x86_64` and `arm64`. Some utilities need an extra, for example `aws-lambda-powertools[parser]` for Pydantic; the [installation guide](https://docs.powertools.aws.dev/lambda/python/latest/getting-started/install/) lists them. + ## Features -Core utilities such as Tracing, Logging, Metrics, and Event Handler are available across all Powertools for AWS Lambda languages. Additional utilities are subjective to each language ecosystem and customer demand. - -* **[Tracing](https://docs.powertools.aws.dev/lambda/python/latest/core/tracer/)** - Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions -* **[Logging](https://docs.powertools.aws.dev/lambda/python/latest/core/logger/)** - Structured logging made easier, and target to enrich structured logging with key Lambda context details -* **[Metrics](https://docs.powertools.aws.dev/lambda/python/latest/core/metrics/)** - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF) -* **[Event handler: AppSync](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/appsync/)** - AppSync event handler for Lambda Direct Resolver and Amplify GraphQL Transformer function -* **[Event handler: AppSync Events](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/appsync_events/)** - AppSync Events handler for real-time WebSocket APIs with pub/sub pattern -* **[Event handler: API Gateway, ALB, Lambda Function URL, VPC Lattice](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/)** - REST/HTTP API event handler for Lambda functions invoked via Amazon API Gateway, ALB, Lambda Function URL, and VPC Lattice -* **[Event handler: Agents for Amazon Bedrock](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/bedrock_agents/)** - Create Agents for Amazon Bedrock, automatically generating OpenAPI schemas -* **[Middleware factory](https://docs.powertools.aws.dev/lambda/python/latest/utilities/middleware_factory/)** - Decorator factory to create your own middleware to run logic before, and after each Lambda invocation -* **[Parameters](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parameters/)** - Retrieve and cache parameter values from Parameter Store, Secrets Manager, AppConfig, or DynamoDB -* **[Batch processing](https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/)** - Handle partial failures for AWS SQS, Kinesis Data Streams, and DynamoDB Streams batch processing -* **[Typing](https://docs.powertools.aws.dev/lambda/python/latest/utilities/typing/)** - Static typing classes to speedup development in your IDE -* **[Validation](https://docs.powertools.aws.dev/lambda/python/latest/utilities/validation/)** - JSON Schema validator for inbound events and responses -* **[Event source data classes](https://docs.powertools.aws.dev/lambda/python/latest/utilities/data_classes/)** - Data classes describing the schema of common Lambda event triggers -* **[Parser](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parser/)** - Data parsing and deep validation using Pydantic -* **[Idempotency](https://docs.powertools.aws.dev/lambda/python/latest/utilities/idempotency/)** - Convert your Lambda functions into idempotent operations which are safe to retry -* **[Data Masking](https://docs.powertools.aws.dev/lambda/python/latest/utilities/data_masking/)** - Protect confidential data with easy removal or encryption -* **[Feature Flags](https://docs.powertools.aws.dev/lambda/python/latest/utilities/feature_flags/)** - A simple rule engine to evaluate when one or multiple features should be enabled depending on the input -* **[Streaming](https://docs.powertools.aws.dev/lambda/python/latest/utilities/streaming/)** - Streams datasets larger than the available memory as streaming data -* **[Kafka](https://docs.powertools.aws.dev/lambda/python/latest/utilities/kafka/)** - Deserialize and validate Kafka events with support for Avro, Protocol Buffers, and JSON Schema -* **[JMESPath Functions](https://docs.powertools.aws.dev/lambda/python/latest/utilities/jmespath_functions/)** - Built-in JMESPath functions to easily deserialize common encoded JSON payloads in Lambda functions - -### Installation - -With [pip](https://pip.pypa.io/en/latest/index.html) installed, run: ``pip install aws-lambda-powertools`` - -## Tutorial and Examples - -* [Tutorial](https://docs.powertools.aws.dev/lambda/python/latest/tutorial) -* [Serverless Shopping cart](https://github.com/aws-samples/aws-serverless-shopping-cart) -* [Serverless Airline](https://github.com/aws-samples/aws-serverless-airline-booking) -* [Serverless E-commerce platform](https://github.com/aws-samples/aws-serverless-ecommerce-platform) -* [Serverless GraphQL Nanny Booking Api](https://github.com/trey-rosius/babysitter_api) +### Core + +* **[Logger](https://docs.powertools.aws.dev/lambda/python/latest/core/logger/)** - Structured JSON logging with Lambda context, correlation IDs, sampling and log buffering +* **[Tracer](https://docs.powertools.aws.dev/lambda/python/latest/core/tracer/)** - Decorators and utilities to trace Lambda function handlers and sync or async functions with AWS X-Ray +* **[Metrics](https://docs.powertools.aws.dev/lambda/python/latest/core/metrics/)** - Custom metrics created asynchronously via CloudWatch Embedded Metric Format (EMF), with a [Datadog](https://docs.powertools.aws.dev/lambda/python/latest/core/metrics/datadog/) provider +* **[Event Handler: REST and HTTP APIs](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/)** - Routing, validation and middleware for API Gateway, ALB, Lambda Function URL and VPC Lattice, with [OpenAPI schema generation and Swagger UI](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/openapi/) +* **[Event Handler: AppSync](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/appsync/)** - Resolvers for AppSync Direct Lambda Resolvers and Amplify GraphQL Transformer functions +* **[Event Handler: AppSync Events](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/appsync_events/)** - Handlers for AppSync Events real-time WebSocket APIs with pub/sub +* **[Event Handler: Bedrock Agents](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/bedrock_agents/)** - Build Amazon Bedrock Agents action groups with automatically generated OpenAPI schemas + +### Utilities + +* **[Parameters](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parameters/)** - Retrieve and cache parameter values from Parameter Store, Secrets Manager, AppConfig or DynamoDB +* **[Idempotency](https://docs.powertools.aws.dev/lambda/python/latest/utilities/idempotency/)** - Make your Lambda functions idempotent and safe to retry, with DynamoDB, Redis or Valkey persistence +* **[Batch processing](https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/)** - Handle partial failures for SQS, Kinesis Data Streams and DynamoDB Streams batches +* **[Circuit Breaker](https://docs.powertools.aws.dev/lambda/python/latest/utilities/circuit_breaker/)** - Stop calling a failing downstream and recover with a single probe across execution environments +* **[Kafka](https://docs.powertools.aws.dev/lambda/python/latest/utilities/kafka/)** - Deserialize and validate Kafka events with Avro, Protocol Buffers and JSON Schema +* **[Event source data classes](https://docs.powertools.aws.dev/lambda/python/latest/utilities/data_classes/)** - Typed access to the payloads of common Lambda event sources +* **[Parser](https://docs.powertools.aws.dev/lambda/python/latest/utilities/parser/)** - Data parsing and deep validation with Pydantic, with models and envelopes for common event sources +* **[Validation](https://docs.powertools.aws.dev/lambda/python/latest/utilities/validation/)** - JSON Schema validation for inbound events and responses +* **[Feature Flags](https://docs.powertools.aws.dev/lambda/python/latest/utilities/feature_flags/)** - A rule engine to evaluate when one or more features should be enabled depending on the input +* **[Data Masking](https://docs.powertools.aws.dev/lambda/python/latest/utilities/data_masking/)** - Erase or encrypt confidential fields in your data with AWS KMS +* **[Auth (alpha)](https://docs.powertools.aws.dev/lambda/python/latest/utilities/auth/)** - JWT access-token verification and an [OAuth2 client-credentials client](https://docs.powertools.aws.dev/lambda/python/latest/utilities/oauth2/) for downstream APIs +* **[Streaming](https://docs.powertools.aws.dev/lambda/python/latest/utilities/streaming/)** - Stream S3 objects larger than the available memory, with gzip, CSV and other transforms +* **[Metadata](https://docs.powertools.aws.dev/lambda/python/latest/utilities/metadata/)** - Read the Lambda Metadata Endpoint, such as the Availability Zone ID of the execution environment +* **[Middleware factory](https://docs.powertools.aws.dev/lambda/python/latest/utilities/middleware_factory/)** - Decorator factory to run your own logic before and after each invocation +* **[Typing](https://docs.powertools.aws.dev/lambda/python/latest/utilities/typing/)** - Static typing for the Lambda context object +* **[JMESPath Functions](https://docs.powertools.aws.dev/lambda/python/latest/utilities/jmespath_functions/)** - Built-in JMESPath functions to deserialize common encoded JSON payloads + +### Lambda features + +* **[Lambda Managed Instances](https://docs.powertools.aws.dev/lambda/python/latest/lambda-features/managed-instances/)** - Using Powertools when one execution environment handles concurrent invocations +* **[Durable Functions](https://docs.powertools.aws.dev/lambda/python/latest/lambda-features/durable-functions/)** - Using Powertools with Lambda Durable Functions +* **[Build recipes](https://docs.powertools.aws.dev/lambda/python/latest/build_recipes/)** - Packaging, cross-platform builds, cold start optimization and CI/CD integration + +## Tutorial and examples + +* [Tutorial](https://docs.powertools.aws.dev/lambda/python/latest/tutorial/) and [workshop](https://s12d.com/powertools-for-aws-lambda-workshop) +* [Examples](https://github.com/aws-powertools/powertools-lambda-python/tree/develop/examples) for every utility, the same code the documentation shows +* [Serverless Airline](https://github.com/aws-samples/aws-serverless-airline-booking), a sample application using Powertools end to end +* [What the community built](https://docs.powertools.aws.dev/lambda/python/latest/we_made_this/): blog posts, workshops, videos and sample apps ## How to support Powertools for AWS Lambda (Python)? @@ -90,13 +107,13 @@ The following companies, among others, use Powertools: Share what you did with Powertools for AWS Lambda (Python) πŸ’žπŸ’ž. Blog post, workshops, presentation, sample apps and others. Check out what the community has already shared about Powertools for AWS Lambda (Python) [in this link](https://docs.powertools.aws.dev/lambda/python/latest/we_made_this/). -### Using Lambda Layer or SAR +### Using the Lambda layer -This helps us understand who uses Powertools for AWS Lambda (Python) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. When [using Layers](https://docs.powertools.aws.dev/lambda/python/latest/#lambda-layer), you can add Powertools for AWS Lambda (Python) as a dev dependency (or as part of your virtual env) to not impact the development process. +Using the [public layer](https://docs.powertools.aws.dev/lambda/python/latest/getting-started/install/#lambda-layer) helps us understand who uses Powertools for AWS Lambda (Python) in a non-intrusive way, and helps us gain future investments for other Powertools for AWS Lambda languages. You can still add Powertools for AWS Lambda (Python) as a dev dependency (or as part of your virtual env) to not impact the development process. ## Contributing -Issues and pull requests are welcome, including the ones written with AI assistance. If you used an assistant, say so in the issue or PR and tell us how you verified the change: which tests you ran yourself, and which real AWS service or event you validated against when it applies. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the process and [AGENTS.md](AGENTS.md) for the rules the CI enforces and the premises behind them. +Issues and pull requests are welcome, including the ones written with AI assistance. If you used an assistant, say so in the issue or PR and tell us how you verified the change: which tests you ran yourself, and which real AWS service or event you validated against when it applies. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the process, [AGENTS.md](AGENTS.md) for the rules the CI enforces, and [docs/adr](docs/adr/README.md) for the premises behind them. ## Credits @@ -110,7 +127,7 @@ Issues and pull requests are welcome, including the ones written with AI assista ## Security disclosures -If you think you’ve found a potential security issue, please do not post it in the Issues. Instead, please follow the instructions [in this link](https://aws.amazon.com/security/vulnerability-reporting/) or [email AWS security directly](mailto:aws-security@amazon.com). +If you think you've found a potential security issue, please do not post it in the Issues. Instead, follow [SECURITY.md](SECURITY.md): report it through the [AWS vulnerability reporting page](https://aws.amazon.com/security/vulnerability-reporting/) or [email AWS security directly](mailto:aws-security@amazon.com). ## License diff --git a/docs/index.md b/docs/index.md index 972919987da..d8ece594d9c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -58,6 +58,7 @@ Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverles | [Parser](./utilities/parser.md) | Data parsing and deep validation using Pydantic | | [Batch Processing](./utilities/batch.md) | Handle partial failures for SQS, Kinesis Data Streams, and DynamoDB Streams | | [Idempotency](./utilities/idempotency.md) | Make your Lambda functions idempotent and prevent duplicate execution | +| [Circuit Breaker](./utilities/circuit_breaker.md) | Stop calling a failing downstream and recover with a single probe across execution environments | | [Feature Flags](./utilities/feature_flags.md) | A simple rule engine to evaluate when features should be enabled | | [Validation](./utilities/validation.md) | JSON Schema validator for inbound events and responses | | [Data Masking](./utilities/data_masking.md) | Protect confidential data with easy removal or encryption | @@ -67,6 +68,7 @@ Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverles | [Event Source Data Classes](./utilities/data_classes.md) | Data classes describing the schema of common Lambda event triggers | | [JMESPath Functions](./utilities/jmespath_functions.md) | Built-in JMESPath functions to deserialize common encoded JSON payloads | | [Kafka](./utilities/kafka.md) | Deserialize and validate Kafka events with support for Avro, Protocol Buffers, and JSON Schema | +| [Metadata](./utilities/metadata.md) | Read the Lambda Metadata Endpoint, such as the Availability Zone ID of the execution environment | ## Examples