Skip to content

refactor(event_handler): promote HttpResolver to stable #8289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
leandrodamascena wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

refactor(event_handler): promote HttpResolver to stable #8289

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3163f27
refactor: promote HttpResolver to stable
leandrodamascena Jun 20, 2026
8ba42a9
refactor: promote HttpResolver to stable
leandrodamascena Jun 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion aws_lambda_powertools/event_handler/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
)
from aws_lambda_powertools.event_handler.depends import DependencyResolutionError, Depends
from aws_lambda_powertools.event_handler.events_appsync.appsync_events import AppSyncEventsResolver
from aws_lambda_powertools.event_handler.http_resolver import HttpResolverLocal
from aws_lambda_powertools.event_handler.http_resolver import HttpResolver, HttpResolverLocal
from aws_lambda_powertools.event_handler.lambda_function_url import (
LambdaFunctionUrlResolver,
)
Expand All @@ -39,6 +39,7 @@
"CORSConfig",
"Depends",
"DependencyResolutionError",
"HttpResolver",
"HttpResolverLocal",
"LambdaFunctionUrlResolver",
"Request",
Expand Down
20 changes: 6 additions & 14 deletions aws_lambda_powertools/event_handler/http_resolver.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
from __future__ import annotations

import base64
import warnings
from typing import TYPE_CHECKING, Any, Callable
from urllib.parse import parse_qs

Expand Down Expand Up @@ -162,21 +161,16 @@ def get_remaining_time_in_millis(self) -> int: # pragma: no cover

class HttpResolverLocal(ApiGatewayResolver):
"""
ASGI-compatible HTTP resolver for local development and testing.
ASGI-compatible HTTP resolver.

This resolver is designed specifically for local development workflows.
It allows you to run your Powertools application locally with any ASGI server
It allows you to run your Powertools application with any ASGI server
(uvicorn, hypercorn, daphne, etc.) while maintaining full compatibility with Lambda.

The same code works in both environments - locally via ASGI and in Lambda via the handler.
If your Lambda is behind Lambda Web Adapter or any other HTTP proxy, it works seamlessly.

Supports both sync and async route handlers.

WARNING
-------
This is intended for local development and testing only.
The API may change in future releases. Do not use in production environments.

Example
-------
```python
Expand Down Expand Up @@ -210,11 +204,6 @@ def __init__(
strip_prefixes: list[str | Any] | None = None,
enable_validation: bool = False,
):
warnings.warn(
"HttpResolverLocal is intended for local development and testing only. "
"The API may change in future releases. Do not use in production environments.",
stacklevel=2,
)
super().__init__(
proxy_type=ProxyEventType.APIGatewayProxyEvent, # Use REST API format internally
cors=cors,
Expand Down Expand Up @@ -351,3 +340,6 @@ async def _send_response(self, send: Callable, response: dict) -> None:
"body": body_bytes,
},
)


HttpResolver = HttpResolverLocal
2 changes: 1 addition & 1 deletion docs/core/event_handler/api_gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ By default, we will use `APIGatewayRestResolver` throughout the documentation. Y
| **[`ALBResolver`](#application-load-balancer)** | Amazon Application Load Balancer (ALB) |
| **[`LambdaFunctionUrlResolver`](#lambda-function-url)** | AWS Lambda Function URL |
| **[`VPCLatticeResolver`](#vpc-lattice)** | Amazon VPC Lattice |
| **[`HttpResolverLocal`](#http-resolver-local)** | Local development with ASGI servers |
| **[`HttpResolverLocal`](#http-resolver-local)** | ASGI-compatible resolver |
<!-- markdownlint-enable MD051 -->

#### Response auto-serialization
Expand Down
8 changes: 2 additions & 6 deletions docs/includes/_http_resolver_local.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,7 @@
<!-- markdownlint-disable MD041 MD043 -->
#### Http Resolver (Local Development)
#### Http Resolver (ASGI)

???+ warning "Local Development Only"
`HttpResolverLocal` is intended for local development and testing only.
The API may change in future releases. **Do not use in production environments.**

When developing locally, you can use `HttpResolverLocal` to run your API with any ASGI server like [uvicorn](https://www.uvicorn.org/){target="_blank"}. It implements the [ASGI specification](https://asgi.readthedocs.io/){target="_blank"}, is lightweight with no external dependencies, and the same code works on any compute platform, including Lambda.
`HttpResolver` is an ASGI-compatible resolver that lets you run your Powertools application with any ASGI server like [uvicorn](https://www.uvicorn.org/){target="_blank"}. It implements the [ASGI specification](https://asgi.readthedocs.io/){target="_blank"}, is lightweight with no external dependencies, and works seamlessly with Lambda or any environment that speaks HTTP.

If your Lambda is behind [Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter){target="_blank"} or any other HTTP proxy that speaks the HTTP protocol, it works seamlessly.

Expand Down
4 changes: 2 additions & 2 deletions examples/event_handler_rest/src/http_resolver_basic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
from aws_lambda_powertools.event_handler import HttpResolverLocal
from aws_lambda_powertools.event_handler import HttpResolver

app = HttpResolverLocal()
app = HttpResolver()


@app.get("/hello/<name>")
Expand Down
4 changes: 2 additions & 2 deletions examples/event_handler_rest/src/http_resolver_exception_handling.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
from aws_lambda_powertools.event_handler import HttpResolverLocal, Response
from aws_lambda_powertools.event_handler import HttpResolver, Response

app = HttpResolverLocal()
app = HttpResolver()


class NotFoundError(Exception):
Expand Down
4 changes: 2 additions & 2 deletions examples/event_handler_rest/src/http_resolver_validation_swagger.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
from pydantic import BaseModel

from aws_lambda_powertools.event_handler import HttpResolverLocal
from aws_lambda_powertools.event_handler import HttpResolver


class User(BaseModel):
name: str
age: int


app = HttpResolverLocal(enable_validation=True)
app = HttpResolver(enable_validation=True)

app.enable_swagger(
title="My API",
Expand Down
4 changes: 0 additions & 4 deletions tests/functional/event_handler/_pydantic/test_http_resolver_pydantic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,6 @@
from aws_lambda_powertools.event_handler.http_resolver import MockLambdaContext
from aws_lambda_powertools.event_handler.openapi.params import Query

# Suppress warning for all tests
pytestmark = pytest.mark.filterwarnings("ignore:HttpResolverLocal is intended for local development")


# =============================================================================
# ASGI Test Helpers
# =============================================================================
Expand Down
6 changes: 1 addition & 5 deletions tests/functional/event_handler/required_dependencies/test_http_resolver.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
"""Tests for HttpResolverLocal - ASGI-compatible HTTP resolver for local development."""
"""Tests for HttpResolverLocal - ASGI-compatible HTTP resolver."""

from __future__ import annotations

Expand All @@ -11,10 +11,6 @@
from aws_lambda_powertools.event_handler import HttpResolverLocal, Response
from aws_lambda_powertools.event_handler.http_resolver import MockLambdaContext

# Suppress warning for all tests
pytestmark = pytest.mark.filterwarnings("ignore:HttpResolverLocal is intended for local development")


# =============================================================================
# ASGI Test Helpers
# =============================================================================
Expand Down