Merge branch 'develop' into develop

Author: heitorlessa

.github/workflows/dependency-review.yml

@@ -19,4 +19,4 @@ jobs:
       - name: 'Checkout Repository'
         uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@1360a344ccb0ab6e9475edef90ad2f46bf8003b1 # v3.0.6
+        uses: actions/dependency-review-action@7d90b4f05fea31dde1c4a1fb3fa787e197ea93ab # v3.0.7

CHANGELOG.md

@@ -12,6 +12,7 @@
 ## Code Refactoring
 
 * **e2e:** support fail fast in get_lambda_response ([#2912](https://github.com/aws-powertools/powertools-lambda-python/issues/2912))
+* **metrics:** move from protocol to ABC; split provider tests ([#2934](https://github.com/aws-powertools/powertools-lambda-python/issues/2934))
 
 ## Documentation
 
@@ -32,38 +33,43 @@
 * **ci:** enable protected branch auditing ([#2913](https://github.com/aws-powertools/powertools-lambda-python/issues/2913))
 * **ci:** group dependabot updates ([#2896](https://github.com/aws-powertools/powertools-lambda-python/issues/2896))
 * **deps:** bump github.com/aws/aws-sdk-go-v2/config from 1.18.28 to 1.18.29 in /layer/scripts/layer-balancer ([#2844](https://github.com/aws-powertools/powertools-lambda-python/issues/2844))
+* **deps:** bump the layer-balancer group in /layer/scripts/layer-balancer with 2 updates ([#2904](https://github.com/aws-powertools/powertools-lambda-python/issues/2904))
 * **deps:** bump squidfunk/mkdocs-material from `33e28bd` to `cd3a522` in /docs ([#2859](https://github.com/aws-powertools/powertools-lambda-python/issues/2859))
+* **deps:** bump slsa-framework/slsa-github-generator from 1.7.0 to 1.8.0 ([#2927](https://github.com/aws-powertools/powertools-lambda-python/issues/2927))
 * **deps:** bump github.com/aws/aws-sdk-go-v2/service/lambda from 1.37.1 to 1.38.0 in /layer/scripts/layer-balancer ([#2843](https://github.com/aws-powertools/powertools-lambda-python/issues/2843))
-* **deps:** bump github.com/aws/aws-sdk-go-v2/config from 1.18.30 to 1.18.31 in /layer/scripts/layer-balancer ([#2889](https://github.com/aws-powertools/powertools-lambda-python/issues/2889))
 * **deps:** bump github.com/aws/aws-sdk-go-v2 from 1.19.0 to 1.19.1 in /layer/scripts/layer-balancer ([#2877](https://github.com/aws-powertools/powertools-lambda-python/issues/2877))
-* **deps:** bump github.com/aws/aws-sdk-go-v2/service/lambda from 1.38.1 to 1.39.0 in /layer/scripts/layer-balancer ([#2890](https://github.com/aws-powertools/powertools-lambda-python/issues/2890))
 * **deps:** bump github.com/aws/aws-sdk-go-v2/service/lambda from 1.38.0 to 1.38.1 in /layer/scripts/layer-balancer ([#2876](https://github.com/aws-powertools/powertools-lambda-python/issues/2876))
-* **deps:** bump the layer-balancer group in /layer/scripts/layer-balancer with 2 updates ([#2904](https://github.com/aws-powertools/powertools-lambda-python/issues/2904))
 * **deps:** bump pydantic from 1.10.11 to 1.10.12 ([#2846](https://github.com/aws-powertools/powertools-lambda-python/issues/2846))
-* **deps:** bump slsa-framework/slsa-github-generator from 1.7.0 to 1.8.0 ([#2927](https://github.com/aws-powertools/powertools-lambda-python/issues/2927))
+* **deps:** bump github.com/aws/aws-sdk-go-v2/config from 1.18.30 to 1.18.31 in /layer/scripts/layer-balancer ([#2889](https://github.com/aws-powertools/powertools-lambda-python/issues/2889))
+* **deps:** bump actions/dependency-review-action from 3.0.6 to 3.0.7 ([#2941](https://github.com/aws-powertools/powertools-lambda-python/issues/2941))
+* **deps:** bump github.com/aws/aws-sdk-go-v2/service/lambda from 1.38.1 to 1.39.0 in /layer/scripts/layer-balancer ([#2890](https://github.com/aws-powertools/powertools-lambda-python/issues/2890))
 * **deps:** bump github.com/aws/aws-sdk-go-v2/config from 1.18.29 to 1.18.30 in /layer/scripts/layer-balancer ([#2875](https://github.com/aws-powertools/powertools-lambda-python/issues/2875))
-* **deps-dev:** bump mypy-boto3-lambda from 1.28.11 to 1.28.15 ([#2878](https://github.com/aws-powertools/powertools-lambda-python/issues/2878))
-* **deps-dev:** bump mypy-boto3-appconfigdata from 1.28.0 to 1.28.15 ([#2879](https://github.com/aws-powertools/powertools-lambda-python/issues/2879))
-* **deps-dev:** bump mypy-boto3-xray from 1.28.0 to 1.28.15 ([#2881](https://github.com/aws-powertools/powertools-lambda-python/issues/2881))
-* **deps-dev:** bump mypy-boto3-logs from 1.28.1 to 1.28.15 ([#2880](https://github.com/aws-powertools/powertools-lambda-python/issues/2880))
+* **deps:** bump the layer-balancer group in /layer/scripts/layer-balancer with 3 updates ([#2933](https://github.com/aws-powertools/powertools-lambda-python/issues/2933))
 * **deps-dev:** bump mkdocs-material from 9.1.19 to 9.1.21 ([#2894](https://github.com/aws-powertools/powertools-lambda-python/issues/2894))
 * **deps-dev:** bump aws-cdk from 2.88.0 to 2.89.0 ([#2887](https://github.com/aws-powertools/powertools-lambda-python/issues/2887))
-* **deps-dev:** bump cfn-lint from 0.79.4 to 0.79.5 ([#2870](https://github.com/aws-powertools/powertools-lambda-python/issues/2870))
+* **deps-dev:** bump mypy-boto3-logs from 1.28.1 to 1.28.15 ([#2880](https://github.com/aws-powertools/powertools-lambda-python/issues/2880))
+* **deps-dev:** bump mypy-boto3-appconfigdata from 1.28.0 to 1.28.15 ([#2879](https://github.com/aws-powertools/powertools-lambda-python/issues/2879))
+* **deps-dev:** bump mypy-boto3-lambda from 1.28.11 to 1.28.15 ([#2878](https://github.com/aws-powertools/powertools-lambda-python/issues/2878))
+* **deps-dev:** bump mypy-boto3-xray from 1.28.0 to 1.28.15 ([#2881](https://github.com/aws-powertools/powertools-lambda-python/issues/2881))
 * **deps-dev:** bump the boto-typing group with 11 updates ([#2901](https://github.com/aws-powertools/powertools-lambda-python/issues/2901))
+* **deps-dev:** bump cfn-lint from 0.79.5 to 0.79.6 ([#2899](https://github.com/aws-powertools/powertools-lambda-python/issues/2899))
+* **deps-dev:** bump sentry-sdk from 1.28.1 to 1.29.0 ([#2900](https://github.com/aws-powertools/powertools-lambda-python/issues/2900))
+* **deps-dev:** bump cfn-lint from 0.79.4 to 0.79.5 ([#2870](https://github.com/aws-powertools/powertools-lambda-python/issues/2870))
+* **deps-dev:** bump ruff from 0.0.280 to 0.0.281 ([#2891](https://github.com/aws-powertools/powertools-lambda-python/issues/2891))
 * **deps-dev:** bump mypy-boto3-cloudformation from 1.28.10 to 1.28.12 ([#2864](https://github.com/aws-powertools/powertools-lambda-python/issues/2864))
 * **deps-dev:** bump mypy-boto3-cloudwatch from 1.28.0 to 1.28.12 ([#2865](https://github.com/aws-powertools/powertools-lambda-python/issues/2865))
 * **deps-dev:** bump cfn-lint from 0.79.3 to 0.79.4 ([#2862](https://github.com/aws-powertools/powertools-lambda-python/issues/2862))
 * **deps-dev:** bump mypy-boto3-appconfig from 1.28.0 to 1.28.12 ([#2861](https://github.com/aws-powertools/powertools-lambda-python/issues/2861))
 * **deps-dev:** bump mypy-boto3-ssm from 1.28.0 to 1.28.12 ([#2863](https://github.com/aws-powertools/powertools-lambda-python/issues/2863))
-* **deps-dev:** bump cfn-lint from 0.79.5 to 0.79.6 ([#2899](https://github.com/aws-powertools/powertools-lambda-python/issues/2899))
-* **deps-dev:** bump sentry-sdk from 1.28.1 to 1.29.0 ([#2900](https://github.com/aws-powertools/powertools-lambda-python/issues/2900))
-* **deps-dev:** bump cfn-lint from 0.78.2 to 0.79.3 ([#2854](https://github.com/aws-powertools/powertools-lambda-python/issues/2854))
-* **deps-dev:** bump mypy-boto3-lambda from 1.28.0 to 1.28.11 ([#2845](https://github.com/aws-powertools/powertools-lambda-python/issues/2845))
-* **deps-dev:** bump ruff from 0.0.280 to 0.0.281 ([#2891](https://github.com/aws-powertools/powertools-lambda-python/issues/2891))
 * **deps-dev:** bump ruff from 0.0.281 to 0.0.282 ([#2905](https://github.com/aws-powertools/powertools-lambda-python/issues/2905))
+* **deps-dev:** bump ruff from 0.0.282 to 0.0.283 ([#2937](https://github.com/aws-powertools/powertools-lambda-python/issues/2937))
+* **deps-dev:** bump cfn-lint from 0.78.2 to 0.79.3 ([#2854](https://github.com/aws-powertools/powertools-lambda-python/issues/2854))
+* **deps-dev:** bump aws-cdk from 2.89.0 to 2.90.0 ([#2932](https://github.com/aws-powertools/powertools-lambda-python/issues/2932))
 * **deps-dev:** bump mypy-boto3-dynamodb from 1.28.0 to 1.28.11 ([#2847](https://github.com/aws-powertools/powertools-lambda-python/issues/2847))
 * **deps-dev:** bump the boto-typing group with 4 updates ([#2928](https://github.com/aws-powertools/powertools-lambda-python/issues/2928))
+* **deps-dev:** bump mypy-boto3-lambda from 1.28.0 to 1.28.11 ([#2845](https://github.com/aws-powertools/powertools-lambda-python/issues/2845))
 * **docs:** disable line length rule using older syntax ([#2920](https://github.com/aws-powertools/powertools-lambda-python/issues/2920))
+* **docs:** include the environment variables section in the utilities documentation ([#2925](https://github.com/aws-powertools/powertools-lambda-python/issues/2925))
 * **maintenance:** enables publishing docs and changelog, running e2e tests only in the main repository ([#2924](https://github.com/aws-powertools/powertools-lambda-python/issues/2924))
 
 

aws_lambda_powertools/metrics/base.py

@@ -17,12 +17,12 @@
     MetricValueError,
     SchemaValidationError,
 )
-from aws_lambda_powertools.metrics.provider.cloudwatch_emf import cold_start
-from aws_lambda_powertools.metrics.provider.cloudwatch_emf.cold_start import (
-    reset_cold_start_flag,  # noqa: F401  # backwards compatibility
-)
+from aws_lambda_powertools.metrics.provider import cold_start
 from aws_lambda_powertools.metrics.provider.cloudwatch_emf.constants import MAX_DIMENSIONS, MAX_METRICS
 from aws_lambda_powertools.metrics.provider.cloudwatch_emf.metric_properties import MetricResolution, MetricUnit
+from aws_lambda_powertools.metrics.provider.cold_start import (
+    reset_cold_start_flag,  # noqa: F401  # backwards compatibility
+)
 from aws_lambda_powertools.metrics.types import MetricNameUnitResolution
 from aws_lambda_powertools.shared import constants
 from aws_lambda_powertools.shared.functions import resolve_env_var_choice

aws_lambda_powertools/metrics/functions.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import List
+
+from aws_lambda_powertools.metrics.provider.cloudwatch_emf.exceptions import (
+    MetricResolutionError,
+    MetricUnitError,
+)
+from aws_lambda_powertools.metrics.provider.cloudwatch_emf.metric_properties import MetricResolution, MetricUnit
+
+
+def extract_cloudwatch_metric_resolution_value(metric_resolutions: List, resolution: int | MetricResolution) -> int:
+    """Return metric value from CloudWatch metric unit whether that's str or MetricResolution enum
+
+    Parameters
+    ----------
+    unit : Union[int, MetricResolution]
+        Metric resolution
+
+    Returns
+    -------
+    int
+        Metric resolution value must be 1 or 60
+
+    Raises
+    ------
+    MetricResolutionError
+        When metric resolution is not supported by CloudWatch
+    """
+    if isinstance(resolution, MetricResolution):
+        return resolution.value
+
+    if isinstance(resolution, int) and resolution in metric_resolutions:
+        return resolution
+
+    raise MetricResolutionError(
+        f"Invalid metric resolution '{resolution}', expected either option: {metric_resolutions}",  # noqa: E501
+    )
+
+
+def extract_cloudwatch_metric_unit_value(metric_units: List, metric_valid_options: List, unit: str | MetricUnit) -> str:
+    """Return metric value from CloudWatch metric unit whether that's str or MetricUnit enum
+
+    Parameters
+    ----------
+    unit : Union[str, MetricUnit]
+        Metric unit
+
+    Returns
+    -------
+    str
+        Metric unit value (e.g. "Seconds", "Count/Second")
+
+    Raises
+    ------
+    MetricUnitError
+        When metric unit is not supported by CloudWatch
+    """
+
+    if isinstance(unit, str):
+        if unit in metric_valid_options:
+            unit = MetricUnit[unit].value
+
+        if unit not in metric_units:
+            raise MetricUnitError(
+                f"Invalid metric unit '{unit}', expected either option: {metric_valid_options}",
+            )
+
+    if isinstance(unit, MetricUnit):
+        unit = unit.value
+
+    return unit

aws_lambda_powertools/metrics/metrics.py

@@ -1,14 +1,15 @@
 # NOTE: keeps for compatibility
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, Optional, Union
+from typing import Any, Callable, Dict, Optional
 
 from aws_lambda_powertools.metrics.base import MetricResolution, MetricUnit
 from aws_lambda_powertools.metrics.provider.cloudwatch_emf.cloudwatch import AmazonCloudWatchEMFProvider
+from aws_lambda_powertools.metrics.provider.cloudwatch_emf.types import CloudWatchEMFOutput
 
 
 class Metrics:
-    """Metrics create an EMF object with up to 100 metrics
+    """Metrics create an CloudWatch EMF object with up to 100 metrics
 
     Use Metrics when you need to create multiple metrics that have
     dimensions in common (e.g. service_name="payment").
@@ -115,7 +116,7 @@ def serialize_metric_set(
         metrics: Dict | None = None,
         dimensions: Dict | None = None,
         metadata: Dict | None = None,
-    ) -> Dict:
+    ) -> CloudWatchEMFOutput:
         return self.provider.serialize_metric_set(metrics=metrics, dimensions=dimensions, metadata=metadata)
 
     def add_metadata(self, key: str, value: Any) -> None:
@@ -138,15 +139,6 @@ def log_metrics(
             default_dimensions=default_dimensions,
         )
 
-    def _extract_metric_resolution_value(self, resolution: Union[int, MetricResolution]) -> int:
-        return self.provider._extract_metric_resolution_value(resolution=resolution)
-
-    def _extract_metric_unit_value(self, unit: Union[str, MetricUnit]) -> str:
-        return self.provider._extract_metric_unit_value(unit=unit)
-
-    def _add_cold_start_metric(self, context: Any) -> None:
-        self.provider._add_cold_start_metric(context=context)
-
     def set_default_dimensions(self, **dimensions) -> None:
         self.provider.set_default_dimensions(**dimensions)
         """Persist dimensions across Lambda invocations
@@ -208,120 +200,3 @@ def service(self, service):
 # we can quickly revert and duplicate code while using self.provider
 
 EphemeralMetrics = AmazonCloudWatchEMFProvider
-
-# noqa: ERA001
-# class EphemeralMetrics(MetricManager):
-#     """Non-singleton version of Metrics to not persist metrics across instances
-#
-#     NOTE: This is useful when you want to:
-#
-#     - Create metrics for distinct namespaces
-#     - Create the same metrics with different dimensions more than once
-#     """
-#
-#     # _dimensions: Dict[str, str] = {}
-#     _default_dimensions: Dict[str, Any] = {}
-#
-#     def __init__(
-#         self,
-#         service: str | None = None,
-#         namespace: str | None = None,
-#         provider: AmazonCloudWatchEMFProvider | None = None,
-#     ):
-#         super().__init__(namespace=namespace, service=service)
-#
-#         self.default_dimensions = self._default_dimensions
-#         # # self.dimension_set = self._dimensions
-#         # self.dimension_set.update(**self._default_dimensions)
-#
-#         self.provider = provider or AmazonCloudWatchEMFProvider(
-#             namespace=namespace,
-#             service=service,
-#             metric_set=self.metric_set,
-#             metadata_set=self.metadata_set,
-#             dimension_set=self.dimension_set,
-#             default_dimensions=self._default_dimensions,
-#         )
-#
-#     def add_metric(
-#         self,
-#         name: str,
-#         unit: MetricUnit | str,
-#         value: float,
-#         resolution: MetricResolution | int = 60,
-#     ) -> None:
-#         return self.provider.add_metric(name=name, unit=unit, value=value, resolution=resolution)
-#
-#     def add_dimension(self, name: str, value: str) -> None:
-#         return self.provider.add_dimension(name=name, value=value)
-#
-#     def serialize_metric_set(
-#         self,
-#         metrics: Dict | None = None,
-#         dimensions: Dict | None = None,
-#         metadata: Dict | None = None,
-#     ) -> Dict:
-#         return self.provider.serialize_metric_set(metrics=metrics, dimensions=dimensions, metadata=metadata)
-#
-#     def add_metadata(self, key: str, value: Any) -> None:
-#         self.provider.add_metadata(key=key, value=value)
-#
-#     def flush_metrics(self, raise_on_empty_metrics: bool = False) -> None:
-#         self.provider.flush_metrics(raise_on_empty_metrics=raise_on_empty_metrics)
-#
-#     def log_metrics(
-#         self,
-#         lambda_handler: Callable[[Dict, Any], Any] | Optional[Callable[[Dict, Any, Optional[Dict]], Any]] = None,
-#         capture_cold_start_metric: bool = False,
-#         raise_on_empty_metrics: bool = False,
-#         default_dimensions: Dict[str, str] | None = None,
-#     ):
-#         return self.provider.log_metrics(
-#             lambda_handler=lambda_handler,
-#             capture_cold_start_metric=capture_cold_start_metric,
-#             raise_on_empty_metrics=raise_on_empty_metrics,
-#             default_dimensions=default_dimensions,
-#         )
-#
-#     def _extract_metric_resolution_value(self, resolution: Union[int, MetricResolution]) -> int:
-#         return self.provider._extract_metric_resolution_value(resolution=resolution)
-#
-#     def _extract_metric_unit_value(self, unit: Union[str, MetricUnit]) -> str:
-#         return self.provider._extract_metric_unit_value(unit=unit)
-#
-#     def _add_cold_start_metric(self, context: Any) -> None:
-#         return self.provider._add_cold_start_metric(context=context)
-#
-#     def set_default_dimensions(self, **dimensions) -> None:
-#         """Persist dimensions across Lambda invocations
-#
-#         Parameters
-#         ----------
-#         dimensions : Dict[str, Any], optional
-#             metric dimensions as key=value
-#
-#         Example
-#         -------
-#         **Sets some default dimensions that will always be present across metrics and invocations**
-#
-#             from aws_lambda_powertools import Metrics
-#
-#             metrics = Metrics(namespace="ServerlessAirline", service="payment")
-#             metrics.set_default_dimensions(environment="demo", another="one")
-#
-#             @metrics.log_metrics()
-#             def lambda_handler():
-#                 return True
-#         """
-#         return self.provider.set_default_dimensions(**dimensions)
-#
-#     def clear_default_dimensions(self) -> None:
-#         self.default_dimensions.clear()
-#
-#     def clear_metrics(self) -> None:
-#         self.provider.clear_metrics()
-#         # re-add default dimensions
-#         self.set_default_dimensions(**self.default_dimensions)
-#
-
-# __all__ = []

aws_lambda_powertools/metrics/provider/__init__.py

@@ -1,6 +1,5 @@
-from aws_lambda_powertools.metrics.provider.base import MetricsBase, MetricsProviderBase
+from aws_lambda_powertools.metrics.provider.base import BaseProvider
 
 __all__ = [
-    "MetricsBase",
-    "MetricsProviderBase",
+    "BaseProvider",
 ]