aws-lambda-powertools 3.0.1.dev3__py3-none-any.whl → 3.0.2.dev1__py3-none-any.whl

aws_lambda_powertools/utilities/data_classes/cognito_user_pool_event.py

@@ -241,6 +241,18 @@ class UserMigrationTriggerEventResponse(DictWrapper):
         """
         self["response"]["forceAliasCreation"] = value
 
+    @property
+    def enable_sms_mfa(self) -> bool | None:
+        return self["response"].get("enableSMSMFA")
+
+    @enable_sms_mfa.setter
+    def enable_sms_mfa(self, value: bool):
+        """Set this parameter to "true" to require that your migrated user complete SMS text message multi-factor
+        authentication (MFA) to sign in. Your user pool must have MFA enabled. Your user's attributes
+        in the request parameters must include a phone number, or else the migration of that user will fail.
+        """
+        self["response"]["enableSMSMFA"] = value
+
 
 class UserMigrationTriggerEvent(BaseTriggerEvent):
     """Migrate User Lambda Trigger
@@ -272,6 +284,11 @@ class CustomMessageTriggerEventRequest(DictWrapper):
         """A string for you to use as the placeholder for the verification code in the custom message."""
         return self["request"]["codeParameter"]
 
+    @property
+    def link_parameter(self) -> str:
+        """A string for you to use as a placeholder for the verification link in the custom message."""
+        return self["request"]["linkParameter"]
+
     @property
     def username_parameter(self) -> str:
         """The username parameter. It is a required request parameter for the admin create user flow."""
@@ -459,7 +476,7 @@ class PreTokenGenerationTriggerEventRequest(DictWrapper):
     @property
     def user_attributes(self) -> dict[str, str]:
         """One or more name-value pairs representing user attributes."""
-        return self["request"]["userAttributes"]
+        return self["request"].get("userAttributes") or {}
 
     @property
     def client_metadata(self) -> dict[str, str]:
@@ -468,6 +485,16 @@ class PreTokenGenerationTriggerEventRequest(DictWrapper):
         return self["request"].get("clientMetadata") or {}
 
 
+class PreTokenGenerationTriggerV2EventRequest(PreTokenGenerationTriggerEventRequest):
+    @property
+    def scopes(self) -> list[str]:
+        """Your user's OAuth 2.0 scopes. The scopes that are present in an access token are
+        the user pool standard and custom scopes that your user requested,
+        and that you authorized your app client to issue.
+        """
+        return self["request"].get("scopes")
+
+
 class ClaimsOverrideDetails(DictWrapper):
     @property
     def claims_to_add_or_override(self) -> dict[str, str]:
@@ -522,6 +549,123 @@ class ClaimsOverrideDetails(DictWrapper):
         self["groupOverrideDetails"]["preferredRole"] = value
 
 
+class TokenClaimsAndScopeOverrideDetails(DictWrapper):
+    @property
+    def claims_to_add_or_override(self) -> dict[str, str]:
+        return self.get("claimsToAddOrOverride") or {}
+
+    @claims_to_add_or_override.setter
+    def claims_to_add_or_override(self, value: dict[str, str]):
+        """A map of one or more key-value pairs of claims to add or override.
+        For group related claims, use groupOverrideDetails instead."""
+        self._data["claimsToAddOrOverride"] = value
+
+    @property
+    def claims_to_suppress(self) -> list[str]:
+        return self.get("claimsToSuppress") or []
+
+    @claims_to_suppress.setter
+    def claims_to_suppress(self, value: list[str]):
+        """A list that contains claims to be suppressed from the identity token."""
+        self._data["claimsToSuppress"] = value
+
+    @property
+    def scopes_to_add(self) -> list[str]:
+        return self.get("scopesToAdd") or []
+
+    @scopes_to_add.setter
+    def scopes_to_add(self, value: list[str]):
+        self._data["scopesToAdd"] = value
+
+    @property
+    def scopes_to_suppress(self) -> list[str]:
+        return self.get("scopesToSuppress") or []
+
+    @scopes_to_suppress.setter
+    def scopes_to_suppress(self, value: list[str]):
+        self._data["scopesToSuppress"] = value
+
+
+class ClaimsAndScopeOverrideDetails(DictWrapper):
+
+    @property
+    def id_token_generation(self) -> TokenClaimsAndScopeOverrideDetails | None:
+        id_token_generation_details = self._data.get("idTokenGeneration")
+        return (
+            None
+            if id_token_generation_details is None
+            else TokenClaimsAndScopeOverrideDetails(id_token_generation_details)
+        )
+
+    @id_token_generation.setter
+    def id_token_generation(self, value: dict[str, Any]):
+        """The output object containing the current id token's claims and scope configuration.
+
+        It includes claimsToAddOrOverride, claimsToSuppress, scopesToAdd and scopesToSupprress.
+
+        The tokenClaimsAndScopeOverrideDetails object is replaced with the one you provide.
+        If you provide an empty or null object in the response, then the groups are suppressed.
+        To leave the existing group configuration as is, copy the value of the token's object
+        to the tokenClaimsAndScopeOverrideDetails object in the response, and pass it back to the service.
+        """
+        self._data["idTokenGeneration"] = value
+
+    @property
+    def access_token_generation(self) -> TokenClaimsAndScopeOverrideDetails | None:
+        access_token_generation_details = self._data.get("accessTokenGeneration")
+        return (
+            None
+            if access_token_generation_details is None
+            else TokenClaimsAndScopeOverrideDetails(access_token_generation_details)
+        )
+
+    @access_token_generation.setter
+    def access_token_generation(self, value: dict[str, Any]):
+        """The output object containing the current access token's claims and scope configuration.
+
+        It includes claimsToAddOrOverride, claimsToSuppress, scopesToAdd and scopesToSupprress.
+
+        The tokenClaimsAndScopeOverrideDetails object is replaced with the one you provide.
+        If you provide an empty or null object in the response, then the groups are suppressed.
+        To leave the existing group configuration as is, copy the value of the token's object to
+        the tokenClaimsAndScopeOverrideDetails object in the response, and pass it back to the service.
+        """
+        self._data["accessTokenGeneration"] = value
+
+    @property
+    def group_configuration(self) -> GroupOverrideDetails | None:
+        group_override_details = self.get("groupOverrideDetails")
+        return None if group_override_details is None else GroupOverrideDetails(group_override_details)
+
+    @group_configuration.setter
+    def group_configuration(self, value: dict[str, Any]):
+        """The output object containing the current group configuration.
+
+        It includes groupsToOverride, iamRolesToOverride, and preferredRole.
+
+        The groupOverrideDetails object is replaced with the one you provide. If you provide an empty or null
+        object in the response, then the groups are suppressed. To leave the existing group configuration
+        as is, copy the value of the request's groupConfiguration object to the groupOverrideDetails object
+        in the response, and pass it back to the service.
+        """
+        self._data["groupOverrideDetails"] = value
+
+    def set_group_configuration_groups_to_override(self, value: list[str]):
+        """A list of the group names that are associated with the user that the identity token is issued for."""
+        self._data.setdefault("groupOverrideDetails", {})
+        self["groupOverrideDetails"]["groupsToOverride"] = value
+
+    def set_group_configuration_iam_roles_to_override(self, value: list[str]):
+        """A list of the current IAM roles associated with these groups."""
+        self._data.setdefault("groupOverrideDetails", {})
+        self["groupOverrideDetails"]["iamRolesToOverride"] = value
+
+    def set_group_configuration_preferred_role(self, value: str):
+        """A string indicating the preferred IAM role."""
+        self._data.setdefault("groupOverrideDetails", {})
+        self["groupOverrideDetails"]["preferredRole"] = value
+
+
 class PreTokenGenerationTriggerEventResponse(DictWrapper):
     @property
     def claims_override_details(self) -> ClaimsOverrideDetails:
@@ -531,6 +675,15 @@ class PreTokenGenerationTriggerEventResponse(DictWrapper):
         return ClaimsOverrideDetails(self._data["response"]["claimsOverrideDetails"])
 
 
+class PreTokenGenerationTriggerV2EventResponse(DictWrapper):
+    @property
+    def claims_scope_override_details(self) -> ClaimsAndScopeOverrideDetails:
+        # Ensure we have a `claimsAndScopeOverrideDetails` element and is not set to None
+        if self._data["response"].get("claimsAndScopeOverrideDetails") is None:
+            self._data["response"]["claimsAndScopeOverrideDetails"] = {}
+        return ClaimsAndScopeOverrideDetails(self._data["response"]["claimsAndScopeOverrideDetails"])
+
+
 class PreTokenGenerationTriggerEvent(BaseTriggerEvent):
     """Pre Token Generation Lambda Trigger
 
@@ -563,6 +716,38 @@ class PreTokenGenerationTriggerEvent(BaseTriggerEvent):
         return PreTokenGenerationTriggerEventResponse(self._data)
 
 
+class PreTokenGenerationV2TriggerEvent(BaseTriggerEvent):
+    """Pre Token Generation Lambda Trigger for the V2 Event
+
+    Amazon Cognito invokes this trigger before token generation allowing you to customize identity token claims.
+
+    Notes:
+    ----
+    `triggerSource` can be one of the following:
+
+    - `TokenGeneration_HostedAuth` Called during authentication from the Amazon Cognito hosted UI sign-in page.
+    - `TokenGeneration_Authentication` Called after user authentication flows have completed.
+    - `TokenGeneration_NewPasswordChallenge` Called after the user is created by an admin. This flow is invoked
+       when the user has to change a temporary password.
+    - `TokenGeneration_AuthenticateDevice` Called at the end of the authentication of a user device.
+    - `TokenGeneration_RefreshTokens` Called when a user tries to refresh the identity and access tokens.
+
+    Documentation:
+    --------------
+    - https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html
+    """
+
+    @property
+    def request(self) -> PreTokenGenerationTriggerV2EventRequest:
+        """Pre Token Generation Request V2 Parameters"""
+        return PreTokenGenerationTriggerV2EventRequest(self._data)
+
+    @property
+    def response(self) -> PreTokenGenerationTriggerV2EventResponse:
+        """Pre Token Generation Response V2 Parameters"""
+        return PreTokenGenerationTriggerV2EventResponse(self._data)
+
+
 class ChallengeResult(DictWrapper):
     @property
     def challenge_name(self) -> str:
@@ -824,3 +1009,77 @@ class VerifyAuthChallengeResponseTriggerEvent(BaseTriggerEvent):
     def response(self) -> VerifyAuthChallengeResponseTriggerEventResponse:
         """Verify Auth Challenge Response Parameters"""
         return VerifyAuthChallengeResponseTriggerEventResponse(self._data)
+
+
+class CustomEmailSenderTriggerEventRequest(DictWrapper):
+    @property
+    def type(self) -> str:
+        """The request version. For a custom email sender event, the value of this string
+        is always customEmailSenderRequestV1.
+        """
+        return self["request"]["type"]
+
+    @property
+    def code(self) -> str:
+        """The encrypted code that your function can decrypt and send to your user."""
+        return self["request"]["code"]
+
+    @property
+    def user_attributes(self) -> dict[str, str]:
+        """One or more name-value pairs representing user attributes. The attribute names are the keys."""
+        return self["request"]["userAttributes"]
+
+    @property
+    def client_metadata(self) -> dict[str, str]:
+        """One or more key-value pairs that you can provide as custom input to the
+        custom email sender Lambda function trigger. To pass this data to your Lambda function,
+        you can use the ClientMetadata parameter in the AdminRespondToAuthChallenge and
+        RespondToAuthChallenge API actions. Amazon Cognito doesn't include data from the
+        ClientMetadata parameter in AdminInitiateAuth and InitiateAuth API operations
+        in the request that it passes to the post authentication function.
+        """
+        return self["request"].get("clientMetadata") or {}
+
+
+class CustomEmailSenderTriggerEvent(BaseTriggerEvent):
+    @property
+    def request(self) -> CustomEmailSenderTriggerEventRequest:
+        """Custom Email Sender Request Parameters"""
+        return CustomEmailSenderTriggerEventRequest(self._data)
+
+
+class CustomSMSSenderTriggerEventRequest(DictWrapper):
+    @property
+    def type(self) -> str:
+        """The request version. For a custom SMS sender event, the value of this string is always
+        customSMSSenderRequestV1.
+        """
+        return self["request"]["type"]
+
+    @property
+    def code(self) -> str:
+        """The encrypted code that your function can decrypt and send to your user."""
+        return self["request"]["code"]
+
+    @property
+    def user_attributes(self) -> dict[str, str]:
+        """One or more name-value pairs representing user attributes. The attribute names are the keys."""
+        return self["request"].get("userAttributes") or {}
+
+    @property
+    def client_metadata(self) -> dict[str, str]:
+        """One or more key-value pairs that you can provide as custom input to the
+        custom SMS sender Lambda function trigger. To pass this data to your Lambda function,
+        you can use the ClientMetadata parameter in the AdminRespondToAuthChallenge and
+        RespondToAuthChallenge API actions. Amazon Cognito doesn't include data from the
+        ClientMetadata parameter in AdminInitiateAuth and InitiateAuth API operations
+        in the request that it passes to the post authentication function.
+        """
+        return self["request"].get("clientMetadata") or {}
+
+
+class CustomSMSSenderTriggerEvent(BaseTriggerEvent):
+    @property
+    def request(self) -> CustomSMSSenderTriggerEventRequest:
+        """Custom SMS Sender Request Parameters"""
+        return CustomSMSSenderTriggerEventRequest(self._data)

aws_lambda_powertools/utilities/data_classes/kafka_event.py

@@ -14,12 +14,12 @@ class KafkaEventRecord(DictWrapper):
         return self["topic"]
 
     @property
-    def partition(self) -> str:
+    def partition(self) -> int:
         """The Kafka record parition."""
         return self["partition"]
 
     @property
-    def offset(self) -> str:
+    def offset(self) -> int:
         """The Kafka record offset."""
         return self["offset"]
 

aws_lambda_powertools/utilities/data_classes/vpc_lattice.py

@@ -193,3 +193,10 @@ class VPCLatticeEventV2(VPCLatticeEventBase):
         """
         params = self.get("queryStringParameters") or {}
         return {k: ",".join(v) for k, v in params.items()}
+
+    @property
+    def resolved_headers_field(self) -> dict[str, str]:
+        if self.headers is not None:
+            return {key.lower(): value for key, value in self.headers.items()}
+
+        return {}

aws_lambda_powertools/utilities/data_masking/base.py

@@ -204,7 +204,7 @@ class DataMasking:
             self._call_action,
             action=action,
             provider_options=provider_options,
-            **encryption_context,
+            **encryption_context,  # type: ignore[arg-type]
         )
 
         # Iterate over each field to be parsed.
@@ -229,12 +229,12 @@ class DataMasking:
                 self._call_action,
                 action=action,
                 provider_options=provider_options,
-                **encryption_context,
+                **encryption_context,  # type: ignore[arg-type]
             )
 
             json_parse.update(
                 data_parsed,
-                lambda field_value, fields, field_name: update_callback(field_value, fields, field_name),  # noqa: B023
+                lambda field_value, fields, field_name: update_callback(field_value, fields, field_name),  # type: ignore[misc] # noqa: B023
             )
 
         return data_parsed
@@ -245,7 +245,7 @@ class DataMasking:
         fields: dict[str, Any],
         field_name: str,
         action: Callable,
-        provider_options: dict | None = None,
+        provider_options: dict[str, Any] | None = None,
         **encryption_context,
     ) -> None:
         """

aws_lambda_powertools/utilities/feature_flags/appconfig.py

@@ -4,6 +4,8 @@ import logging
 import traceback
 from typing import TYPE_CHECKING, Any, cast
 
+from botocore.config import Config
+
 from aws_lambda_powertools.utilities import jmespath_utils
 from aws_lambda_powertools.utilities.feature_flags.base import StoreProvider
 from aws_lambda_powertools.utilities.feature_flags.exceptions import ConfigurationStoreError, StoreClientError
@@ -14,7 +16,9 @@ from aws_lambda_powertools.utilities.parameters import (
 )
 
 if TYPE_CHECKING:
+    import boto3
     from botocore.config import Config
+    from mypy_boto3_appconfigdata import AppConfigDataClient
 
     from aws_lambda_powertools.logging import Logger
 
@@ -30,6 +34,9 @@ class AppConfigStore(StoreProvider):
         envelope: str | None = "",
         jmespath_options: dict | None = None,
         logger: logging.Logger | Logger | None = None,
+        boto_config: Config | None = None,
+        boto3_session: boto3.session.Session | None = None,
+        boto3_client: AppConfigDataClient | None = None,
     ):
         """This class fetches JSON schemas from AWS AppConfig
 
@@ -51,6 +58,12 @@ class AppConfigStore(StoreProvider):
             Alternative JMESPath options to be included when filtering expr
         logger: A logging object
             Used to log messages. If None is supplied, one will be created.
+        boto_config: botocore.config.Config, optional
+            Botocore configuration to pass during client initialization
+        boto3_session : boto3.Session, optional
+            Boto3 session to use for AWS API communication
+        boto3_client : AppConfigDataClient, optional
+            Boto3 AppConfigDataClient Client to use, boto3_session and boto_config will be ignored if both are provided
         """
         super().__init__()
         self.logger = logger or logging.getLogger(__name__)
@@ -58,10 +71,16 @@ class AppConfigStore(StoreProvider):
         self.application = application
         self.name = name
         self.cache_seconds = max_age
-        self.config = sdk_config
+        self.config = sdk_config or boto_config
         self.envelope = envelope
         self.jmespath_options = jmespath_options
-        self._conf_store = AppConfigProvider(environment=environment, application=application, boto_config=sdk_config)
+        self._conf_store = AppConfigProvider(
+            environment=environment,
+            application=application,
+            config=sdk_config or boto_config,
+            boto3_client=boto3_client,
+            boto3_session=boto3_session,
+        )
 
     @property
     def get_raw_configuration(self) -> dict[str, Any]:

aws_lambda_powertools/utilities/idempotency/idempotency.py

@@ -7,11 +7,13 @@ from __future__ import annotations
 import functools
 import logging
 import os
+import warnings
 from inspect import isclass
 from typing import TYPE_CHECKING, Any, Callable, cast
 
 from aws_lambda_powertools.middleware_factory import lambda_handler_decorator
 from aws_lambda_powertools.shared import constants
+from aws_lambda_powertools.shared.functions import strtobool
 from aws_lambda_powertools.shared.types import AnyCallableT
 from aws_lambda_powertools.utilities.idempotency.base import IdempotencyHandler
 from aws_lambda_powertools.utilities.idempotency.config import IdempotencyConfig
@@ -26,6 +28,8 @@ if TYPE_CHECKING:
     )
     from aws_lambda_powertools.utilities.typing import LambdaContext
 
+from aws_lambda_powertools.warnings import PowertoolsUserWarning
+
 logger = logging.getLogger(__name__)
 
 
@@ -70,7 +74,15 @@ def idempotent(
         >>>     return {"StatusCode": 200}
     """
 
-    if os.getenv(constants.IDEMPOTENCY_DISABLED_ENV):
+    # Skip idempotency controls when POWERTOOLS_IDEMPOTENCY_DISABLED has a truthy value
+    # Raises a warning if not running in development mode
+    if strtobool(os.getenv(constants.IDEMPOTENCY_DISABLED_ENV, "false")):
+        warnings.warn(
+            message="Disabling idempotency is intended for development environments only "
+            "and should not be used in production.",
+            category=PowertoolsUserWarning,
+            stacklevel=2,
+        )
         return handler(event, context, **kwargs)
 
     config = config or IdempotencyConfig()
@@ -154,7 +166,15 @@ def idempotent_function(
 
     @functools.wraps(function)
     def decorate(*args, **kwargs):
-        if os.getenv(constants.IDEMPOTENCY_DISABLED_ENV):
+        # Skip idempotency controls when POWERTOOLS_IDEMPOTENCY_DISABLED has a truthy value
+        # Raises a warning if not running in development mode
+        if strtobool(os.getenv(constants.IDEMPOTENCY_DISABLED_ENV, "false")):
+            warnings.warn(
+                message="Disabling idempotency is intended for development environments only "
+                "and should not be used in production.",
+                category=PowertoolsUserWarning,
+                stacklevel=2,
+            )
             return function(*args, **kwargs)
 
         if data_keyword_argument not in kwargs:

aws_lambda_powertools/utilities/idempotency/persistence/base.py

@@ -305,7 +305,10 @@ class BasePersistenceLayer(ABC):
             payload_hash=self._get_hashed_payload(data=data),
         )
 
-        if remaining_time_in_millis:
+        # When Lambda kills the container after timeout, the remaining_time_in_millis is 0, which is considered False.
+        # Therefore, we need to check if remaining_time_in_millis is not None (>=0) to handle this case.
+        # See: https://github.com/aws-powertools/powertools-lambda-python/issues/4759
+        if remaining_time_in_millis is not None:
             now = datetime.datetime.now()
             period = datetime.timedelta(milliseconds=remaining_time_in_millis)
             timestamp = (now + period).timestamp()

aws_lambda_powertools/utilities/parameters/secrets.py

@@ -432,7 +432,7 @@ def set_secret(
         >>> parameters.set_secret(
                 name="my-secret",
                 value='{"password": "supers3cr3tllam@passw0rd"}',
-                client_request_token="61f2af5f-5f75-44b1-a29f-0cc37af55b11"
+                client_request_token="YOUR_TOKEN_HERE"
             )
 
     URLs:

aws_lambda_powertools/utilities/parser/models/__init__.py

@@ -1,11 +1,14 @@
 from .alb import AlbModel, AlbRequestContext, AlbRequestContextData
 from .apigw import (
+    ApiGatewayAuthorizerRequest,
+    ApiGatewayAuthorizerToken,
     APIGatewayEventAuthorizer,
     APIGatewayEventIdentity,
     APIGatewayEventRequestContext,
     APIGatewayProxyEventModel,
 )
 from .apigwv2 import (
+    ApiGatewayAuthorizerRequestV2,
     APIGatewayProxyEventV2Model,
     RequestContextV2,
     RequestContextV2Authorizer,
@@ -101,6 +104,7 @@ from .vpc_latticev2 import VpcLatticeV2Model
 
 __all__ = [
     "APIGatewayProxyEventV2Model",
+    "ApiGatewayAuthorizerRequestV2",
     "RequestContextV2",
     "RequestContextV2Http",
     "RequestContextV2Authorizer",
@@ -161,6 +165,8 @@ __all__ = [
     "APIGatewayEventRequestContext",
     "APIGatewayEventAuthorizer",
     "APIGatewayEventIdentity",
+    "ApiGatewayAuthorizerRequest",
+    "ApiGatewayAuthorizerToken",
     "KafkaSelfManagedEventModel",
     "KafkaRecordModel",
     "KafkaMskEventModel",

aws_lambda_powertools/utilities/parser/models/apigw.py

@@ -88,5 +88,16 @@ class APIGatewayProxyEventModel(BaseModel):
     requestContext: APIGatewayEventRequestContext
     pathParameters: Optional[Dict[str, str]] = None
     stageVariables: Optional[Dict[str, str]] = None
-    isBase64Encoded: bool
+    isBase64Encoded: Optional[bool] = None
     body: Optional[Union[str, Type[BaseModel]]] = None
+
+
+class ApiGatewayAuthorizerToken(BaseModel):
+    type: Literal["TOKEN"]
+    methodArn: str
+    authorizationToken: str
+
+
+class ApiGatewayAuthorizerRequest(APIGatewayProxyEventModel):
+    type: Literal["REQUEST"]
+    methodArn: str

aws_lambda_powertools/utilities/parser/models/apigwv2.py

@@ -66,4 +66,10 @@ class APIGatewayProxyEventV2Model(BaseModel):
     stageVariables: Optional[Dict[str, str]] = None
     requestContext: RequestContextV2
     body: Optional[Union[str, Type[BaseModel]]] = None
-    isBase64Encoded: bool
+    isBase64Encoded: Optional[bool] = None
+
+
+class ApiGatewayAuthorizerRequestV2(APIGatewayProxyEventV2Model):
+    type: Literal["REQUEST"]
+    routeArn: str
+    identitySource: List[str]

aws_lambda_powertools/utilities/validation/base.py

@@ -9,7 +9,13 @@ from aws_lambda_powertools.utilities.validation.exceptions import InvalidSchemaF
 logger = logging.getLogger(__name__)
 
 
-def validate_data_against_schema(data: dict | str, schema: dict, formats: dict | None = None):
+def validate_data_against_schema(
+    data: dict | str,
+    schema: dict,
+    formats: dict | None = None,
+    handlers: dict | None = None,
+    provider_options: dict | None = None,
+) -> dict | str:
     """Validate dict data against given JSON Schema
 
     Parameters
@@ -20,6 +26,17 @@ def validate_data_against_schema(data: dict | str, schema: dict, formats: dict |
         JSON Schema to validate against
     formats: dict
         Custom formats containing a key (e.g. int64) and a value expressed as regex or callback returning bool
+    handlers: Dict
+        Custom methods to retrieve remote schemes, keyed off of URI scheme
+    provider_options: Dict
+        Arguments that will be passed directly to the underlying validation call, in this case fastjsonchema.validate.
+        For all supported arguments see: https://horejsek.github.io/python-fastjsonschema/#fastjsonschema.validate
+
+    Returns
+    -------
+    Dict
+        The validated event. If the schema specifies a `default` value for fields that are omitted,
+        those default values will be included in the response.
 
     Raises
     ------
@@ -30,7 +47,15 @@ def validate_data_against_schema(data: dict | str, schema: dict, formats: dict |
     """
     try:
         formats = formats or {}
-        fastjsonschema.validate(definition=schema, data=data, formats=formats)
+        handlers = handlers or {}
+        provider_options = provider_options or {}
+        return fastjsonschema.validate(
+            definition=schema,
+            data=data,
+            formats=formats,
+            handlers=handlers,
+            **provider_options,
+        )
     except (TypeError, AttributeError, fastjsonschema.JsonSchemaDefinitionException) as e:
         raise InvalidSchemaFormatError(f"Schema received: {schema}, Formats: {formats}. Error: {e}")
     except fastjsonschema.JsonSchemaValueException as e: