refactor(metrics): Improve type annotations for metrics decorator

[leandrodamascena]

Issue number: #4088

Summary

Changes

Description

This PR improves type annotations for the metrics decorator @metrics.log_metrics. While we strive to enhance type safety, it's important to note that supporting strict typing is a best-effort approach and not guaranteed in Powertools.

This new annotation type supports dependency injection scenario as well. We cannot anticipate all possible return types for a Lambda function, so the best approach is to define Callable[..., Any] as the expected return for this decorator.

from typing import Any
from aws_lambda_powertools import Metrics, Logger
from aws_lambda_powertools.utilities.typing import LambdaContext

metrics = Metrics()
logger = Logger()


@metrics.log_metrics(capture_cold_start_metric=True) 
def lambda_handler(event: Any, context: LambdaContext, logger: Logger | None = None) -> dict[str, Any]:
    return {"a": "b"}

(venv) ➜  mymetrics mypy --strict metricsnew.py 
Success: no issues found in 1 source file

User experience

This will improve pyright/mypy errors report.

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

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

All modified and coverable lines are covered by tests ✅

Project coverage is 96.24%. Comparing base (02a2490) to head (3a3c3ed).
Report is 3 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #6000   +/-   ##
========================================
  Coverage    96.24%   96.24%           
========================================
  Files          234      234           
  Lines        11016    11016           
  Branches       798      798           
========================================
  Hits         10602    10602           
  Misses         327      327           
  Partials        87       87           

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

[anafalcao]

approved 👏

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
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