feat(event_handler): add Dependency injection with Depends()

[leandrodamascena]

Issue number: closes #8099

Summary

This PR add Depends() for type-safe dependency injection in route handlers using the Annotated pattern. Dependencies are declared inline in the function signature - no decorators, no global state. This also supports nested dependencies, per-invocation caching, Request injection, and dependency_overrides for easy testing.

User experience

Before this, sharing services like a DynamoDB table across handlers required append_context - untyped, no IDE support, manual setup in every handler.

Now you declare what a handler needs directly in its signature:

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.openapi.params import Depends
from aws_lambda_powertools.utilities.typing import LambdaContext

app = APIGatewayHttpResolver()


def get_dynamodb_resource():
    return boto3.resource("dynamodb")


def get_orders_table(dynamodb: Annotated[Any, Depends(get_dynamodb_resource)]):
    return dynamodb.Table(os.environ["ORDERS_TABLE"])


def get_users_table(dynamodb: Annotated[Any, Depends(get_dynamodb_resource)]):
    return dynamodb.Table(os.environ["USERS_TABLE"])


@app.get("/orders/<user_id>")
def get_user_orders(
    user_id: str,
    orders_table: Annotated[Any, Depends(get_orders_table)],
    users_table: Annotated[Any, Depends(get_users_table)],
):
    user = users_table.get_item(Key={"pk": user_id})["Item"]
    orders = orders_table.query(KeyConditionExpression="pk = :uid", ExpressionAttributeValues={":uid": user_id})
    return {"user": user["name"], "orders": orders["Items"]}


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

The resolver handles the rest: resolving, caching, and injecting. Dependencies can depend on other dependencies, and the whole tree is resolved automatically.

For testing, swap any dependency without monkeypatching:

app.dependency_overrides[get_dynamodb_table] = lambda: mock_table

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[codecov]

Codecov Report

❌ Patch coverage is 98.16514% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.68%. Comparing base (f1d07ab) to head (48bdeb0).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
aws_lambda_powertools/event_handler/depends.py	98.73%	0 Missing and 1 partial ⚠️
..._lambda_powertools/event_handler/openapi/params.py	90.90%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #8128      +/-   ##
===========================================
+ Coverage    96.64%   96.68%   +0.04%     
===========================================
  Files          284      285       +1     
  Lines        14079    14187     +108     
  Branches      1153     1175      +22     
===========================================
+ Hits         13606    13717     +111     
+ Misses         344      341       -3     
  Partials       129      129              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[leandrodamascena]

Hey @svozza can you pls review again?

[svozza]

Not sure if you want to handle the Sonarqube waring about complexity but other than that looks good to me

[leandrodamascena]

Not sure if you want to handle the Sonarqube waring about complexity but other than that looks good to me

Thanks for approving this! I have this issue #7895. I'll start working on this in the next week. There are a bunch of them that I want to fix.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud