Skip to content

Releases: aws-powertools/powertools-lambda-python

v3.29.0

04 May 12:43
@github-actions github-actions
v3.29.0
245ac2d

Choose a tag to compare

View all tags
v3.29.0 Latest
Latest

Summary

We're thrilled to announce native async resolution for the Event Handler. Write async def route handlers, call await app.resolve_async(event, context), and mix sync/async middlewares. Everything runs natively on the event loop.

We also fixed OpenAPI schema generation for Pydantic @computed_field, a deadlock when sync middlewares raised before calling next(), and ALB returning 422 when response body is None.

A huge thanks to @hirenkumar-n-dholariya, @amrabed, and @catarinacps for their contributions!

Async Event Handler with resolve_async()

Docs

You can now define async route handlers and resolve them without blocking the event loop.

Even though the Lambda handler itself is sync, you can use asyncio.run(app.resolve_async(event, context)) to fan out multiple I/O calls concurrently with asyncio.gather or call async libraries directly.

import asyncio

from aws_lambda_powertools.event_handler import APIGatewayHttpResolver
from aws_lambda_powertools.utilities.typing import LambdaContext

app = APIGatewayHttpResolver()

async def get_orders(user_id: str) -> list:
    ...

async def get_profile(user_id: str) -> dict:
    ...

@app.get("/dashboard/<user_id>")
async def get_dashboard(user_id: str):
    orders, profile = await asyncio.gather(
        get_orders(user_id),
        get_profile(user_id),
    )
    return {"orders": orders, "profile": profile}


def lambda_handler(event: dict, context: LambdaContext):
    return asyncio.run(app.resolve_async(event, context))

Sync and async middlewares work together seamlessly. Sync middlewares are bridged to the event loop in a background thread, so you don't need to rewrite existing middleware to adopt async handlers.

OpenAPI computed_field support

Docs

Pydantic @computed_field properties now appear in generated OpenAPI schemas. Previously they were excluded because we always used mode="validation" when generating JSON schemas.

from pydantic import BaseModel, computed_field

from aws_lambda_powertools.event_handler import APIGatewayHttpResolver

app = APIGatewayHttpResolver(enable_validation=True)


class Order(BaseModel):
    price: float
    quantity: int

    @computed_field
    @property
    def total(self) -> float:
        return self.price * self.quantity


@app.get("/order")
def get_order() -> Order:
    return Order(price=10.0, quantity=3)

Last but not least, thanks to @chriselion and @avplab for reporting bugs in our Event Handler resolvers.

Changes

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@amrabed, @catarinacps, @dependabot[bot], @github-actions[bot], @hirenkumar-n-dholariya, @leandrodamascena, dependabot[bot] and github-actions[bot]

Contributors

amrabed, leandrodamascena, and 5 other contributors
Assets 3
Loading

v3.28.0

15 Apr 14:17
@github-actions github-actions
v3.28.0
9f2c57d

Choose a tag to compare

View all tags
v3.28.0

Summary

This release brings dependency injection, an enriched Request object, OpenAPI improvements, and internal refactoring to the Event Handler.

  • Dependency injection: type-safe Depends() with nested resolution, caching, and test overrides
  • Enriched Request: resolved_event and context properties bridge middleware and dependencies
  • OpenAPI status_code: set default response status code on route decorators
  • Query string fix: parameters no longer dropped when both single and multi-value query strings are present

A huge thanks to @JustinBerger, @Iamrodos, and @ran-isenberg for their contributions!

Dependency injection with Depends()

Docs

You can now use Depends() to declare typed dependencies directly in route handler signatures: no decorators, no global state. Dependencies are resolved automatically, cached per invocation, and support nested dependency trees.

import os
from typing import Any

import boto3
from typing_extensions import Annotated

from aws_lambda_powertools.event_handler import APIGatewayHttpResolver
from aws_lambda_powertools.event_handler.depends import Depends
from aws_lambda_powertools.utilities.typing import LambdaContext

app = APIGatewayHttpResolver()


def get_dynamodb_table():
    dynamodb = boto3.resource("dynamodb")
    return dynamodb.Table(os.environ["TABLE_NAME"])


@app.get("/orders")
def list_orders(table: Annotated[Any, Depends(get_dynamodb_table)]):
    return table.scan()["Items"]

For testing, swap any dependency without monkeypatching:

app.dependency_overrides[get_dynamodb_table] = lambda: mock_table

Enriched Request object

Docs

The Request object now exposes resolved_event and context, enabling dependency functions to access the full Powertools event and bridge data with middleware.

from typing_extensions import Annotated

from aws_lambda_powertools.event_handler import APIGatewayHttpResolver, Response
from aws_lambda_powertools.event_handler.depends import Depends
from aws_lambda_powertools.event_handler.request import Request

app = APIGatewayHttpResolver()


# Middleware handles auth: can return HTTP responses (redirects, 401s)
def auth_middleware(app, next_middleware):
    token = app.current_event.headers.get("authorization", "")
    if not token:
        return Response(status_code=401, body="Unauthorized")

    app.append_context(user={"id": "user-123", "role": "admin"})
    return next_middleware(app)


app.use(middlewares=[auth_middleware])


# Depends() reads what middleware wrote via request.context
def get_current_user(request: Request) -> dict:
    return request.context["user"]


@app.get("/admin/dashboard")
def admin_dashboard(user: Annotated[dict, Depends(get_current_user)]):
    return {"message": f"Welcome {user['id']}", "role": user["role"]}

OpenAPI status_code field

Docs

You can now set the default response status code directly on route decorators. This is reflected in the generated OpenAPI schema and Swagger UI.

from aws_lambda_powertools.event_handler import APIGatewayRestResolver

app = APIGatewayRestResolver(enable_validation=True)


@app.post(
    "/todos",
    summary="Creates a new todo item",
    status_code=201,
    tags=["Todos"],
)
def create_todo(title: str) -> dict:
    return {"id": 1, "title": title}

Changes

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@JustinBerger, @dependabot[bot], @github-actions[bot], @leandrodamascena, dependabot[bot] and github-actions[bot]

Contributors

leandrodamascena, Iamrodos, and 3 other contributors
Loading

v3.27.0

06 Apr 15:08
@github-actions github-actions
v3.27.0
31d0872

Choose a tag to compare

View all tags
v3.27.0

Summary

In this release, we focused on the Event Handler utility - we added three new features and shipped several important bug fixes across Event Handler and Idempotency.

  • File uploads - handle multipart/form-data uploads with full OpenAPI validation and Swagger UI file picker
  • Cookie parameters - use cookies as typed, validated parameters alongside Query(), Header(), and Form()
  • Request object - access the resolved route pattern, path parameters, and HTTP method in middleware and route handlers

A huge thanks to @oyiz-michael, @siwyd, @abhu85, and @danjhd for their contributions!

File upload support for OpenAPI

Docs

You can now handle file uploads in your API endpoints with full OpenAPI validation and Swagger UI support. If using Swagger, it renders a file picker automatically. A special thanks to @oyiz-michael for starting the initial work on this feature.

from typing import Annotated

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import File, Form, UploadFile

app = APIGatewayRestResolver(enable_validation=True)
app.enable_swagger(path="/swagger")


@app.post("/upload")
def upload(
    file_data: Annotated[UploadFile, File(description="CSV file")],
    separator: Annotated[str, Form(description="CSV separator")] = ",",
):
    return {
        "filename": file_data.filename,
        "content_type": file_data.content_type,
        "file_size": len(file_data),
    }

You can receive files as raw bytes (Annotated[bytes, File()]) or as an UploadFile object with filename and content type metadata.

Cookie parameter support for OpenAPI

Docs

You can now use cookies as typed, validated parameters in your API endpoints - just like Query(), Header(), or Form(). The OpenAPI schema generates in: cookie parameters automatically, and validation works across all resolver types.

from typing import Annotated

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import Cookie

app = APIGatewayRestResolver(enable_validation=True)


@app.get("/me")
def get_me(
    session_id: Annotated[str, Cookie(description="Session identifier")],
    theme: Annotated[str, Cookie(description="UI theme")] = "light",
):
    return {"session_id": session_id, "theme": theme}

Request object for middleware and route handlers

Docs

We added a Request object that gives middleware and route handlers access to the resolved route pattern, Powertools-extracted path parameters, HTTP method, headers, query parameters, and body. Previously, middleware only had access to app.current_event, which returns raw API Gateway parameters (e.g. {"proxy": "users/123"} for {proxy+} routes) instead of the resolved ones.

You can access the Request object in two ways:

In middleware via app.request:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response
from aws_lambda_powertools.event_handler.middlewares import NextMiddleware

app = APIGatewayRestResolver()


def auth_middleware(app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> Response:
    req = app.request
    route = req.route              # "/users/{user_id}"
    path_params = req.path_parameters  # {"user_id": "123"}
    method = req.method            # "GET"

    # auth logic here...
    return next_middleware(app)


app.use(middlewares=[auth_middleware])

In route handlers via type annotation:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Request

app = APIGatewayRestResolver()


@app.get("/users/<user_id>")
def get_user(user_id: str, request: Request):
    user_agent = request.headers.get("user-agent")
    return {"id": user_id, "route": request.route, "user_agent": user_agent}

Changes

  • feat(event_handler): add Cookie parameter support for OpenAPI utility (#8095) by @leandrodamascena
  • fix(data_classes): support {proxy+} and path parameters in authorizer response (#8092) by @leandrodamascena
  • fix(event_handler): sync middleware receives real response in async ASGI context (#8089) by @leandrodamascena
  • feat(event_handler): add Request object for middleware access to resolved route and args (#8036) by @oyiz-michael
  • fix(event_handler): support finding type annotated resolver when merging schemas (#8074) by @siwyd
  • fix(idempotency): serialize Pydantic models with mode='json' for UUID/date support (#8075) by @abhu85
  • fix(event_handler): normalize Union and RootModel sequences in body validation (#8067) by @danjhd

📜 Documentation updates

🔧 Maintenance

This release was made possible by the following contributors:

@abhu85, @danjhd, @dependabot[bot], @github-actions[bot], @leandrodamascena, @oyiz-michael, @ran-isenberg, @siwyd, dependabot[bot] and github-actions[bot]

Contributors

siwyd, leandrodamascena, and 5 other contributors
Loading

v3.26.0

23 Mar 16:00
@github-actions github-actions
v3.26.0
f59417a

Choose a tag to compare

View all tags
v3.26.0

Summary

In this release, we are pleased to announce a new utility for interacting with the Lambda Metadata Service, allowing you to easily retrieve information about the Lambda function, such as the Availability Zone ID.

A huge thanks to @acascell, @shaked-lokits, @maxrabin, and @amin-farjadi, for their contributions 🚀🌟

Lambda Metadata Service

Docs

You can now use get_lambda_metadata() function fetch metadata from the AWS Lambda Metadata endpoint, such as the Availability Zone ID. Results are cached for the sandbox lifetime and the utility automatically returns empty metadata outside of Lambda, so your code works seamlessly in local development and testing.

from aws_lambda_powertools import Logger
from aws_lambda_powertools.utilities.metadata import LambdaMetadata, get_lambda_metadata
from aws_lambda_powertools.utilities.typing import LambdaContext

logger = Logger()


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    metadata: LambdaMetadata = get_lambda_metadata()
    az_id = metadata.availability_zone_id  # e.g., "use1-az1"

    logger.append_keys(az_id=az_id)
    logger.info("Processing request")

    return {"az_id": az_id}

Changes

📜 Documentation updates

🐛 Bug and hot fixes

🔧 Maintenance

This release was made possible by the following contributors:

@acascell, @amin-farjadi, @dependabot[bot], @github-actions[bot], @leandrodamascena, @shaked-lokits, dependabot[bot] and github-actions[bot]

Contributors

maxrabin, leandrodamascena, and 4 other contributors
Loading

v3.25.0

12 Mar 11:35
@github-actions github-actions
v3.25.0
464de77

Choose a tag to compare

View all tags
v3.25.0

Summary

This release introduces per-route validation support in event handler, durable context support for logger and metric decorators, multiple dimension sets in metrics, S3 IntelligentTiering event support, and a URL-decode flag for ALB query parameters. We also shipped several important bug fixes across logger, parameters, event handler, and typing.

A huge thanks to @oyiz-michael, @chriselion, @maxrabin, @facu-01, and @Iamrodos, for their contributions 🚀🌟

Per-route validation support

Docs

You can now enable or disable validation on individual routes. This is useful when migrating incrementally - enable validation globally and opt-out specific legacy routes, or vice versa.

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from pydantic import BaseModel

app = APIGatewayRestResolver(enable_validation=True)

class Todo(BaseModel):
    title: str
    completed: bool

# This route has validation enabled (inherits from resolver)
@app.post("/todos")
def create_todo(todo: Todo) -> dict:
    return {"title": todo.title}

# This route opts out of validation
@app.get("/legacy", enable_validation=False)
def legacy_endpoint():
    return {"message": "no validation here"}

Durable Context support in Logger and Metrics decorators

Docs

Logger and Metrics decorators now handle AWS Lambda Durable Context automatically. When a durable function replays, the decorators unwrap the DurableContext to access the underlying Lambda context - no changes needed in your code.

from aws_lambda_powertools import Logger, Metrics
from aws_lambda_powertools.metrics import MetricUnit

logger = Logger()
metrics = Metrics()

@logger.inject_lambda_context  # automatically handles DurableContext
@metrics.log_metrics            # automatically handles DurableContext
def lambda_handler(event, context):
    logger.info("Processing event")
    metrics.add_metric(name="InvocationCount", unit=MetricUnit.Count, value=1)
    return {"statusCode": 200}

Multiple dimension sets in Metrics

Docs

You can now publish metrics with multiple dimension sets using add_dimensions(). Each call creates a new dimension set in the CloudWatch EMF output.

from aws_lambda_powertools import Metrics
from aws_lambda_powertools.metrics import MetricUnit

metrics = Metrics()

@metrics.log_metrics
def lambda_handler(event, context):
    metrics.add_metric(name="OrderCount", unit=MetricUnit.Count, value=1)

    # Each call creates a separate dimension set
    metrics.add_dimensions(environment="prod", region="us-east-1")
    metrics.add_dimensions(service="orders", team="backend")

ALB URL-decode query parameters

Docs

A new decode_query_parameters flag in ALBResolver automatically URL-decodes query parameter keys and values.

from aws_lambda_powertools.event_handler import ALBResolver

app = ALBResolver(decode_query_parameters=True)

@app.get("/search")
def search():
    # Query params are automatically URL-decoded
    query = app.current_event.query_string_parameters
    return {"query": query}

Changes

🌟New features and non-breaking changes

📜 Documentation updates

  • chore(deps): bump squidfunk/mkdocs-material from 3bba0a9 to 8f41b60 in /docs (#8010) by @dependabot[bot]
  • docs: clarify append_context_keys behavior with overlapping keys (#7846) by @oyiz-michael

🐛 Bug and hot fixes

  • fix(logger): preserve percent-style formatting args in flush_buffer (#8009) by @dreamorosi
  • fix(parameters): fix variable shadowing in SSM parameter chunking (#8006) by @dreamorosi
  • fix(event_handler): return 415 status_code for unsupported content-type headers (#7980) by @chriselion
  • fix(typing): resolve ty diagnostics in logging and metrics modules (#7953) by @ConnorKirk
  • fix(event-handler): prevent OpenAPI schema bleed when reusing response dictionaries (#7952) by @oyiz-michael
  • fix(event_handler): sync alias and validation_alias for Pydantic 2.12+ compatibility (#7901) by @leandrodamascena
  • fix(typing): accept Mapping type in resolve() for event parameter (#7909) by @Iamrodos
  • fix(event_handler): fix bug regression in Annotated field (#7904) by @leandrodamascena
  • fix(event_handler): preserve openapi_examples on Body (#7862) by @facu-01

🔧 Maintenance

Read more

Contributors

maxrabin, leandrodamascena, and 7 other contributors
Loading

v3.24.0

05 Jan 13:44
@github-actions github-actions
v3.24.0
d561d12

Choose a tag to compare

View all tags
v3.24.0

Summary

This release adds support for Lambda durable function replay in idempotency, a new parser model for DynamoDB Stream on-failure destinations, and a fix for batch processor. We've also dropped Python 3.9 support.

A super thanks to @ConnorKirk for implementing the idempotency replay feature and @exg for the batch processor fix and DynamoDB Stream parser model 🚀🌟

Idempotency: Allow durable functions to replay

Docs

AWS Lambda durable functions enable you to build resilient multi-step applications that can execute for up to one year while maintaining reliable progress despite interruptions. When a durable function resumes from a wait point or interruption, the system performs replay - running your code from the beginning but skipping completed checkpoints.

This release adds support for durable function replay in idempotency. When using the @idempotent decorator on lambda_handler, replay is automatically detected from the DurableContext - no manual configuration needed.

from aws_lambda_powertools.utilities.idempotency import idempotent, DynamoDBPersistenceLayer, IdempotencyConfig

persistence_layer = DynamoDBPersistenceLayer(table_name="idempotency_store")
config = IdempotencyConfig(event_key_jmespath="body")

@idempotent(config=config, persistence_store=persistence_layer)
def lambda_handler(event, context):
    # Replay is automatically detected when context is a DurableContext
    # During replay, INPROGRESS records are handled gracefully
    return {"statusCode": 200}

DynamoDB Stream On-Failure Destination parser model

Docs

A new parser model DynamoDBStreamLambdaOnFailureDestinationModel is now available for parsing DynamoDB Stream on-failure destination events.

from aws_lambda_powertools.utilities.parser import parse
from aws_lambda_powertools.utilities.parser.models import DynamoDBStreamLambdaOnFailureDestinationModel

def lambda_handler(event, context):
    parsed = parse(event=event, model=DynamoDBStreamLambdaOnFailureDestinationModel)
    
    batch_info = parsed.ddb_stream_batch_info
    print(f"Failed batch from shard: {batch_info.shard_id}")
    print(f"Stream ARN: {batch_info.stream_arn}")

Changes

  • refactor(event-handler): remove kwargs from AppSync exception constructor (#7699) by @T90REAL

🌟New features and non-breaking changes

📜 Documentation updates

  • docs(homepage): reorganize homepage and create dedicated installation page (#7896) by @leandrodamascena
  • docs(readme): update features list and improve readability (#7889) by @leandrodamascena
  • feat(parser): add model for the DynamoDB Stream Lambda invocation record (#7818) by @exg
  • docs(event-handler): add docstring for serializer in BedrockAgentFunctionResolver (#7808) by @dreamorosi
  • docs: add EF Education First as customer reference (#7809) by @dreamorosi
  • docs: clarify BedrockResponse.is_json() always returns True (#7748) by @oyiz-michael

🐛 Bug and hot fixes

  • fix(batch_processor): fix batch processor (#7798) by @exg
  • fix(data-classes): ensure lazy initialization for Cognito token generation response properties (#7653) by @nc-dirknilius
  • fix(ci): add missing dollar signs in SSM parameter path variables (#7695) by @Iamrodos

🔧 Maintenance

Read more

Contributors

exg, leandrodamascena, and 7 other contributors
Loading

v3.23.0

19 Nov 09:32
@github-actions github-actions
v3.23.0
de63d62

Choose a tag to compare

View all tags
v3.23.0

Summary

In this release we added support for the newly released Python 3.14 AWS Lambda managed runtime 🚀.

Changes

  • refactor(event-handler): remove kwargs from AppSync exception constructor (#7699) by @T90REAL

📜 Documentation updates

  • docs(openapi): Update docstring's openapi default version to match current default version (#7669) by @victorperezpiqueras
  • docs(batch): fix error handling code highlight line number (#7638) by @ConnorKirk

🐛 Bug and hot fixes

🔧 Maintenance

This release was made possible by the following contributors:

@ConnorKirk, @Iamrodos, @T90REAL, @dependabot[bot], @dreamorosi, @github-actions[bot], @leandrodamascena, @victorperezpiqueras, dependabot[bot] and github-actions[bot]

Contributors

leandrodamascena, Iamrodos, and 5 other contributors
Loading

v3.22.1

06 Nov 09:45
@github-actions github-actions
v3.22.1
f6bc9d9

Choose a tag to compare

View all tags
v3.22.1

Summary

In this release, we fixed a regression introduced by PR #7227 that affected customers using the Event Handler utility with nested metadata annotations such as annotated_types or Interval. Thanks to @rtandy for identifying the bug and validating the fix.

We also fixed small bugs in type annotations and in our documentation.

⭐ Congrats @rpivo and @czechnology for contributing to this project for the first time!

Changes

📜 Documentation updates

  • docs(batch): fix error handling code highlight line number (#7638) by @ConnorKirk
  • docs(tracer): fix typo in the tracer documentation (#7617) by @rpivo

🐛 Bug and hot fixes

🔧 Maintenance

This release was made possible by the following contributors:

@ConnorKirk, @czechnology, @dependabot[bot], @github-actions[bot], @leandrodamascena, @mahveotm, @rpivo, dependabot[bot] and github-actions[bot]

Contributors

rtandy, czechnology, and 5 other contributors
Loading

v3.22.0

21 Oct 11:32
@github-actions github-actions
v3.22.0
635892e

Choose a tag to compare

View all tags
v3.22.0

Summary

This release enhances our Event Handler with support for Pydantic Models when validating query strings and headers parameters. This addition brings type safety, automatic validation, and better developer experience to your API endpoints.

A super thanks to @tonnico for implementing this important feature 🚀 🌟

📜 Announcement: You can now find our documentation on the official AWS documentation domain at docs.aws.amazon.com/powertools/python.

Using Pydantic models to validate query strings and headers parameters

Docs

You can now use Pydantic's models to validate query strings and headers parameters. This allows you to have structured, type-safe validation with automatic error handling and clear validation messages.

Why this important:

  • Type safety: Catch validation errors at runtime with clear error messages
  • Developer experience: Get IDE autocompletion and type hints for your parameters
  • Documentation: Self-documenting code through Pydantic model definitions
  • Model reusability: Use the same validation model across multiple endpoints for consistency
carbon (19)

Changes

🌟New features and non-breaking changes

  • feat(event_handler): add support for Pydantic models in Query and Header types (#7253) by @tonnico

📜 Documentation updates

🐛 Bug and hot fixes

  • fix(event_handler): Preserve examples field in OpenAPI schema for BedrockAgentResolver (#7561) by @leandrodamascena

🔧 Maintenance

This release was made possible by the following contributors:

@ConnorKirk, @dependabot[bot], @github-actions[bot], @leandrodamascena, @sthulb, @tonnico, dependabot[bot] and github-actions[bot]

Contributors

sthulb, leandrodamascena, and 3 other contributors
Loading

v3.21.0

10 Oct 12:51
@github-actions github-actions
v3.21.0
e5011ef

Choose a tag to compare

View all tags
v3.21.0

Summary

This release enhances our Event Handler with support for Pydantic Field discriminators and improved OpenAPI response capabilities. We've also expanded our Parser utility with better AppSync and CloudWatch models, plus important bug fixes for form data handling.

⭐️ Congrats to @dap0am, @tonnico, @sreejaaryahi18, @aalvrzf, @Iamrodos, and @dcabib for contributing to this release!

Pydantic Field discriminator support

Docs

You can now use Pydantic's discriminator feature in your Event Handler validation. This allows you to handle polymorphic data structures with union types more efficiently.

union

Enhanced OpenAPI responses

The OpenAPI utility now supports richer response definitions including headers, links, examples, and encoding specifications, giving you more control over your API documentation.

Changes

  • refactor(parser): Improve AppSync models with examples and descriptions (#7330) by @dcabib

🌟New features and non-breaking changes

  • feat(event_handler): enhance OpenAPI response with headers, links, examples and encoding (#7312) by @dcabib
  • feat(parser): add field metadata and examples for CloudWatch models (#7343) by @sreejaaryahi18

📜 Documentation updates

🐛 Bug and hot fixes

  • fix(event_handler): parse single list items in form data (#7415) by @tonnico
  • fix(docs): correct build optimization script and docs (#7367) by @Iamrodos

🔧 Maintenance

Read more

Contributors

hjgraca, leandrodamascena, and 8 other contributors
Loading