aws-lambda-powertools 3.5.1a8__tar.gz → 3.6.0__tar.gz

{aws_lambda_powertools-3.5.1a8 → aws_lambda_powertools-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: aws_lambda_powertools
-Version: 3.5.1a8
+Version: 3.6.0
 Summary: Powertools for AWS Lambda (Python) is a developer toolkit to implement Serverless best practices and increase developer velocity.
 License: MIT
 Keywords: aws_lambda_powertools,aws,tracing,logging,lambda,powertools,feature_flags,idempotency,middleware

{aws_lambda_powertools-3.5.1a8 → aws_lambda_powertools-3.6.0}/aws_lambda_powertools/metrics/functions.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from datetime import datetime
 
 from aws_lambda_powertools.metrics.provider.cloudwatch_emf.exceptions import (
@@ -8,6 +9,7 @@ from aws_lambda_powertools.metrics.provider.cloudwatch_emf.exceptions import (
 )
 from aws_lambda_powertools.metrics.provider.cloudwatch_emf.metric_properties import MetricResolution, MetricUnit
 from aws_lambda_powertools.shared import constants
+from aws_lambda_powertools.shared.functions import strtobool
 
 
 def extract_cloudwatch_metric_resolution_value(metric_resolutions: list, resolution: int | MetricResolution) -> int:
@@ -134,3 +136,28 @@ def convert_timestamp_to_emf_format(timestamp: int | datetime) -> int:
         # Returning zero represents the initial date of epoch time,
         # which will be skipped by Amazon CloudWatch.
         return 0
+
+
+def is_metrics_disabled() -> bool:
+    """
+    Determine if metrics should be disabled based on environment variables.
+
+    Returns:
+        bool: True if metrics are disabled, False otherwise.
+
+    Rules:
+    - If POWERTOOLS_DEV is True and POWERTOOLS_METRICS_DISABLED is True: Disable metrics
+    - If POWERTOOLS_METRICS_DISABLED is True: Disable metrics
+    - If POWERTOOLS_DEV is True and POWERTOOLS_METRICS_DISABLED is not set: Disable metrics
+    """
+
+    is_dev_mode = strtobool(os.getenv(constants.POWERTOOLS_DEV_ENV, "false"))
+    is_metrics_disabled = strtobool(os.getenv(constants.METRICS_DISABLED_ENV, "false"))
+
+    disable_conditions = [
+        is_metrics_disabled,
+        is_metrics_disabled and is_dev_mode,
+        is_dev_mode and os.getenv(constants.METRICS_DISABLED_ENV) is None,
+    ]
+
+    return any(disable_conditions)

{aws_lambda_powertools-3.5.1a8 → aws_lambda_powertools-3.6.0}/aws_lambda_powertools/metrics/metrics.py

@@ -47,6 +47,8 @@ class Metrics:
         metric namespace
     POWERTOOLS_SERVICE_NAME : str
         service name used for default dimension
+    POWERTOOLS_METRICS_DISABLED: bool
+        Powertools metrics disabled (e.g. `"true", "True", "TRUE"`)
 
     Parameters
     ----------

{aws_lambda_powertools-3.5.1a8 → aws_lambda_powertools-3.6.0}/aws_lambda_powertools/metrics/provider/cloudwatch_emf/cloudwatch.py

@@ -15,6 +15,7 @@ from aws_lambda_powertools.metrics.functions import (
     convert_timestamp_to_emf_format,
     extract_cloudwatch_metric_resolution_value,
     extract_cloudwatch_metric_unit_value,
+    is_metrics_disabled,
     validate_emf_timestamp,
 )
 from aws_lambda_powertools.metrics.provider.base import BaseProvider
@@ -77,6 +78,7 @@ class AmazonCloudWatchEMFProvider(BaseProvider):
         self.default_dimensions = default_dimensions or {}
         self.namespace = resolve_env_var_choice(choice=namespace, env=os.getenv(constants.METRICS_NAMESPACE_ENV))
         self.service = resolve_env_var_choice(choice=service, env=os.getenv(constants.SERVICE_NAME_ENV))
+
         self.metadata_set = metadata_set if metadata_set is not None else {}
         self.timestamp: int | None = None
 
@@ -127,6 +129,7 @@ class AmazonCloudWatchEMFProvider(BaseProvider):
         MetricResolutionError
             When metric resolution is not supported by CloudWatch
         """
+
         if not isinstance(value, numbers.Number):
             raise MetricValueError(f"{value} is not a valid number")
 
@@ -268,6 +271,7 @@ class AmazonCloudWatchEMFProvider(BaseProvider):
         value : str
             Dimension value
         """
+
         logger.debug(f"Adding dimension: {name}:{value}")
         if len(self.dimension_set) == MAX_DIMENSIONS:
             raise SchemaValidationError(
@@ -374,7 +378,7 @@ class AmazonCloudWatchEMFProvider(BaseProvider):
                 "If application metrics should never be empty, consider using 'raise_on_empty_metrics'",
                 stacklevel=2,
             )
-        else:
+        elif not is_metrics_disabled():
             logger.debug("Flushing existing metrics")
             metrics = self.serialize_metric_set()
             print(json.dumps(metrics, separators=(",", ":")))

{aws_lambda_powertools-3.5.1a8 → aws_lambda_powertools-3.6.0}/aws_lambda_powertools/metrics/provider/datadog/datadog.py

@@ -10,6 +10,7 @@ import warnings
 from typing import TYPE_CHECKING, Any
 
 from aws_lambda_powertools.metrics.exceptions import MetricValueError, SchemaValidationError
+from aws_lambda_powertools.metrics.functions import is_metrics_disabled
 from aws_lambda_powertools.metrics.provider import BaseProvider
 from aws_lambda_powertools.metrics.provider.datadog.warnings import DatadogDataValidationWarning
 from aws_lambda_powertools.shared import constants
@@ -99,7 +100,6 @@ class DatadogProvider(BaseProvider):
             >>>     sales='sam'
             >>> )
         """
-
         # validating metric name
         if not self._validate_datadog_metric_name(name):
             docs = "https://docs.datadoghq.com/metrics/custom_metrics/#naming-custom-metrics"
@@ -180,6 +180,7 @@ class DatadogProvider(BaseProvider):
         raise_on_empty_metrics : bool, optional
             raise exception if no metrics are emitted, by default False
         """
+
         if not raise_on_empty_metrics and len(self.metric_set) == 0:
             warnings.warn(
                 "No application metrics to publish. The cold-start metric may be published if enabled. "
@@ -200,7 +201,7 @@ class DatadogProvider(BaseProvider):
                         timestamp=metric_item["e"],
                         tags=metric_item["t"],
                     )
-            else:
+            elif not is_metrics_disabled():
                 # dd module not found: flush to log, this format can be recognized via datadog log forwarder
                 # https://github.com/Datadog/datadog-lambda-python/blob/main/datadog_lambda/metric.py#L77
                 for metric_item in metrics:

{aws_lambda_powertools-3.5.1a8 → aws_lambda_powertools-3.6.0}/aws_lambda_powertools/shared/constants.py

@@ -40,6 +40,7 @@ LAMBDA_LOG_LEVEL_ENV: str = "AWS_LAMBDA_LOG_LEVEL"
 METRICS_NAMESPACE_ENV: str = "POWERTOOLS_METRICS_NAMESPACE"
 DATADOG_FLUSH_TO_LOG: str = "DD_FLUSH_TO_LOG"
 SERVICE_NAME_ENV: str = "POWERTOOLS_SERVICE_NAME"
+METRICS_DISABLED_ENV: str = "POWERTOOLS_METRICS_DISABLED"
 # If the timestamp of log event is more than 2 hours in future, the log event is skipped.
 # If the timestamp of log event is more than 14 days in past, the log event is skipped.
 # See https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AgentReference.html

{aws_lambda_powertools-3.5.1a8 → aws_lambda_powertools-3.6.0}/aws_lambda_powertools/shared/version.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.5.1a8"
+VERSION = "3.6.0"

{aws_lambda_powertools-3.5.1a8 → aws_lambda_powertools-3.6.0}/aws_lambda_powertools/utilities/data_classes/api_gateway_authorizer_event.py

@@ -5,7 +5,7 @@ import re
 import warnings
 from typing import Any, overload
 
-from typing_extensions import deprecated
+from typing_extensions import deprecated, override
 
 from aws_lambda_powertools.utilities.data_classes.common import (
     BaseRequestContext,
@@ -28,9 +28,10 @@ class APIGatewayRouteArn:
         aws_account_id: str,
         api_id: str,
         stage: str,
-        http_method: str,
+        http_method: str | None,
         resource: str,
         partition: str = "aws",
+        is_websocket_authorizer: bool = False,
     ):
         self.partition = partition
         self.region = region
@@ -40,39 +41,54 @@ class APIGatewayRouteArn:
         self.http_method = http_method
         # Remove matching "/" from `resource`.
         self.resource = resource.lstrip("/")
+        self.is_websocket_authorizer = is_websocket_authorizer
 
     @property
     def arn(self) -> str:
         """Build an arn from its parts
         eg: arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request"""
-        return (
-            f"arn:{self.partition}:execute-api:{self.region}:{self.aws_account_id}:{self.api_id}/{self.stage}/"
-            f"{self.http_method}/{self.resource}"
-        )
+        base_arn = f"arn:{self.partition}:execute-api:{self.region}:{self.aws_account_id}:{self.api_id}/{self.stage}"
+
+        if not self.is_websocket_authorizer:
+            return f"{base_arn}/{self.http_method}/{self.resource}"
+        else:
+            return f"{base_arn}/{self.resource}"
 
 
-def parse_api_gateway_arn(arn: str) -> APIGatewayRouteArn:
+def parse_api_gateway_arn(arn: str, is_websocket_authorizer: bool = False) -> APIGatewayRouteArn:
     """Parses a gateway route arn as a APIGatewayRouteArn class
 
     Parameters
     ----------
     arn : str
         ARN string for a methodArn or a routeArn
+    is_websocket_authorizer: bool
+        If it's a API Gateway Websocket
+
     Returns
     -------
     APIGatewayRouteArn
     """
     arn_parts = arn.split(":")
     api_gateway_arn_parts = arn_parts[5].split("/")
+
+    if not is_websocket_authorizer:
+        http_method = api_gateway_arn_parts[2]
+        resource = "/".join(api_gateway_arn_parts[3:]) if len(api_gateway_arn_parts) >= 4 else ""
+    else:
+        http_method = None
+        resource = "/".join(api_gateway_arn_parts[2:])
+
     return APIGatewayRouteArn(
         partition=arn_parts[1],
         region=arn_parts[3],
         aws_account_id=arn_parts[4],
         api_id=api_gateway_arn_parts[0],
         stage=api_gateway_arn_parts[1],
-        http_method=api_gateway_arn_parts[2],
+        http_method=http_method,
         # conditional allow us to handle /path/{proxy+} resources, as their length changes.
-        resource="/".join(api_gateway_arn_parts[3:]) if len(api_gateway_arn_parts) >= 4 else "",
+        resource=resource,
+        is_websocket_authorizer=is_websocket_authorizer,
     )
 
 
@@ -512,13 +528,14 @@ class APIGatewayAuthorizerResponse:
             raise ValueError(f"Invalid resource path: {resource}. Path should match {self.path_regex}")
 
         resource_arn = APIGatewayRouteArn(
-            self.region,
-            self.aws_account_id,
-            self.api_id,
-            self.stage,
-            http_method,
-            resource,
-            self.partition,
+            region=self.region,
+            aws_account_id=self.aws_account_id,
+            api_id=self.api_id,
+            stage=self.stage,
+            http_method=http_method,
+            resource=resource,
+            partition=self.partition,
+            is_websocket_authorizer=False,
         ).arn
 
         route = {"resourceArn": resource_arn, "conditions": conditions}
@@ -617,3 +634,127 @@ class APIGatewayAuthorizerResponse:
             response["context"] = self.context
 
         return response
+
+
+class APIGatewayAuthorizerResponseWebSocket(APIGatewayAuthorizerResponse):
+    """The IAM Policy Response required for API Gateway WebSocket APIs
+
+    Based on: - https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints/blob/\
+    master/blueprints/python/api-gateway-authorizer-python.py
+
+    Documentation:
+    -------------
+    - https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html
+    - https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-lambda-authorizer-output.html
+    """
+
+    @staticmethod
+    def from_route_arn(
+        arn: str,
+        principal_id: str,
+        context: dict | None = None,
+        usage_identifier_key: str | None = None,
+    ) -> APIGatewayAuthorizerResponseWebSocket:
+        parsed_arn = parse_api_gateway_arn(arn, is_websocket_authorizer=True)
+        return APIGatewayAuthorizerResponseWebSocket(
+            principal_id,
+            parsed_arn.region,
+            parsed_arn.aws_account_id,
+            parsed_arn.api_id,
+            parsed_arn.stage,
+            context,
+            usage_identifier_key,
+        )
+
+    # Note: we need ignore[override] because we are removing the http_method field
+    @override
+    def _add_route(self, effect: str, resource: str, conditions: list[dict] | None = None):  # type: ignore[override]
+        """Adds a route to the internal lists of allowed or denied routes. Each object in
+        the internal list contains a resource ARN and a condition statement. The condition
+        statement can be null."""
+        resource_arn = APIGatewayRouteArn(
+            region=self.region,
+            aws_account_id=self.aws_account_id,
+            api_id=self.api_id,
+            stage=self.stage,
+            http_method=None,
+            resource=resource,
+            partition=self.partition,
+            is_websocket_authorizer=True,
+        ).arn
+
+        route = {"resourceArn": resource_arn, "conditions": conditions}
+
+        if effect.lower() == "allow":
+            self._allow_routes.append(route)
+        else:  # deny
+            self._deny_routes.append(route)
+
+    @override
+    def allow_all_routes(self):
+        """Adds a '*' allow to the policy to authorize access to all methods of an API"""
+        self._add_route(effect="Allow", resource="*")
+
+    @override
+    def deny_all_routes(self):
+        """Adds a '*' allow to the policy to deny access to all methods of an API"""
+
+        self._add_route(effect="Deny", resource="*")
+
+    # Note: we need ignore[override] because we are removing the http_method field
+    @override
+    def allow_route(self, resource: str, conditions: list[dict] | None = None):  # type: ignore[override]
+        """
+        Add an API Gateway Websocket method to the list of allowed methods for the policy.
+
+        This method adds an API Gateway Websocket method Resource path) to the list of
+        allowed methods for the policy. It optionally includes conditions for the policy statement.
+
+        Parameters
+        ----------
+        resource : str
+            The API Gateway resource path to allow.
+        conditions : list[dict] | None, optional
+            A list of condition dictionaries to apply to the policy statement.
+            Default is None.
+
+        Notes
+        -----
+        For more information on AWS policy conditions, see:
+        https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html#Condition
+
+        Example
+        --------
+        >>> policy = APIGatewayAuthorizerResponseWebSocket(...)
+        >>> policy.allow_route("/api/users", [{"StringEquals": {"aws:RequestTag/Environment": "Production"}}])
+        """
+        self._add_route(effect="Allow", resource=resource, conditions=conditions)
+
+    # Note: we need ignore[override] because we are removing the http_method field
+    @override
+    def deny_route(self, resource: str, conditions: list[dict] | None = None):  # type: ignore[override]
+        """
+        Add an API Gateway Websocket method to the list of allowed methods for the policy.
+
+        This method adds an API Gateway Websocket method Resource path) to the list of
+        denied methods for the policy. It optionally includes conditions for the policy statement.
+
+        Parameters
+        ----------
+        resource : str
+            The API Gateway resource path to allow.
+        conditions : list[dict] | None, optional
+            A list of condition dictionaries to apply to the policy statement.
+            Default is None.
+
+        Notes
+        -----
+        For more information on AWS policy conditions, see:
+        https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html#Condition
+
+        Example
+        --------
+        >>> policy = APIGatewayAuthorizerResponseWebSocket(...)
+        >>> policy.deny_route("/api/users", [{"StringEquals": {"aws:RequestTag/Environment": "Production"}}])
+        """
+        self._add_route(effect="Deny", resource=resource, conditions=conditions)