aws-lambda-powertools 3.5.1a9__tar.gz → 3.6.1a0__tar.gz

{aws_lambda_powertools-3.5.1a9 → aws_lambda_powertools-3.6.1a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: aws_lambda_powertools
-Version: 3.5.1a9
+Version: 3.6.1a0
 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.1a9 → aws_lambda_powertools-3.6.1a0}/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.1a9 → aws_lambda_powertools-3.6.1a0}/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.1a9 → aws_lambda_powertools-3.6.1a0}/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.1a9 → aws_lambda_powertools-3.6.1a0}/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.1a9 → aws_lambda_powertools-3.6.1a0}/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.1a9 → aws_lambda_powertools-3.6.1a0}/aws_lambda_powertools/shared/version.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.5.1a9"
+VERSION = "3.6.1a0"

{aws_lambda_powertools-3.5.1a9 → aws_lambda_powertools-3.6.1a0}/aws_lambda_powertools/utilities/data_masking/base.py

@@ -9,7 +9,8 @@ from __future__ import annotations
 import functools
 import logging
 import warnings
-from typing import TYPE_CHECKING, Any, Callable, Mapping, Sequence, overload
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, Callable, Mapping, Sequence
 
 from jsonpath_ng.ext import parse
 
@@ -18,6 +19,7 @@ from aws_lambda_powertools.utilities.data_masking.exceptions import (
     DataMaskingUnsupportedTypeError,
 )
 from aws_lambda_powertools.utilities.data_masking.provider import BaseProvider
+from aws_lambda_powertools.warnings import PowertoolsUserWarning
 
 if TYPE_CHECKING:
     from numbers import Number
@@ -67,11 +69,39 @@ class DataMasking:
         provider_options: dict | None = None,
         **encryption_context: str,
     ) -> str:
+        """
+        Encrypt data using the configured encryption provider.
+
+        Parameters
+        ----------
+        data : dict, Mapping, Sequence, or Number
+            The data to encrypt.
+        provider_options : dict, optional
+            Provider-specific options for encryption.
+        **encryption_context : str
+            Additional key-value pairs for encryption context.
+
+        Returns
+        -------
+        str
+            The encrypted data as a base64-encoded string.
+
+        Example
+        --------
+
+            encryption_provider = AWSEncryptionSDKProvider(keys=[KMS_KEY_ARN])
+            data_masker = DataMasking(provider=encryption_provider)
+            encrypted = data_masker.encrypt({"secret": "value"})
+        """
         return self._apply_action(
             data=data,
             fields=None,
             action=self.provider.encrypt,
             provider_options=provider_options or {},
+            dynamic_mask=None,
+            custom_mask=None,
+            regex_pattern=None,
+            mask_format=None,
             **encryption_context,
         )
 
@@ -81,28 +111,91 @@ class DataMasking:
         provider_options: dict | None = None,
         **encryption_context: str,
     ) -> Any:
+        """
+        Decrypt data using the configured encryption provider.
+
+        Parameters
+        ----------
+        data : dict, Mapping, Sequence, or Number
+            The data to encrypt.
+        provider_options : dict, optional
+            Provider-specific options for encryption.
+        **encryption_context : str
+            Additional key-value pairs for encryption context.
+
+        Returns
+        -------
+        str
+            The encrypted data as a base64-encoded string.
+
+        Example
+        --------
+
+            encryption_provider = AWSEncryptionSDKProvider(keys=[KMS_KEY_ARN])
+            data_masker = DataMasking(provider=encryption_provider)
+            encrypted = data_masker.decrypt(encrypted_data)
+        """
+
         return self._apply_action(
             data=data,
             fields=None,
             action=self.provider.decrypt,
             provider_options=provider_options or {},
+            dynamic_mask=None,
+            custom_mask=None,
+            regex_pattern=None,
+            mask_format=None,
             **encryption_context,
         )
 
-    @overload
-    def erase(self, data, fields: None) -> str: ...
-
-    @overload
-    def erase(self, data: list, fields: list[str]) -> list[str]: ...
-
-    @overload
-    def erase(self, data: tuple, fields: list[str]) -> tuple[str]: ...
+    def erase(
+        self,
+        data: Any,
+        fields: list[str] | None = None,
+        *,
+        dynamic_mask: bool | None = None,
+        custom_mask: str | None = None,
+        regex_pattern: str | None = None,
+        mask_format: str | None = None,
+        masking_rules: dict | None = None,
+    ) -> Any:
+        """
+        Erase or mask sensitive data in the input.
 
-    @overload
-    def erase(self, data: dict, fields: list[str]) -> dict: ...
+        Parameters
+        ----------
+        data : Any
+            The data to be erased or masked.
+        fields : list of str, optional
+            List of field names to be erased or masked.
+        dynamic_mask : bool, optional
+            Whether to use dynamic masking.
+        custom_mask : str, optional
+            Custom mask to apply instead of the default.
+        regex_pattern : str, optional
+            Regular expression pattern for identifying data to mask.
+        mask_format : str, optional
+            Format string for the mask.
+        masking_rules : dict, optional
+            Dictionary of custom masking rules.
 
-    def erase(self, data: Sequence | Mapping, fields: list[str] | None = None) -> str | list[str] | tuple[str] | dict:
-        return self._apply_action(data=data, fields=fields, action=self.provider.erase)
+        Returns
+        -------
+        Any
+            The data with sensitive information erased or masked.
+        """
+        if masking_rules:
+            return self._apply_masking_rules(data=data, masking_rules=masking_rules)
+        else:
+            return self._apply_action(
+                data=data,
+                fields=fields,
+                action=self.provider.erase,
+                dynamic_mask=dynamic_mask,
+                custom_mask=custom_mask,
+                regex_pattern=regex_pattern,
+                mask_format=mask_format,
+            )
 
     def _apply_action(
         self,
@@ -110,8 +203,12 @@ class DataMasking:
         fields: list[str] | None,
         action: Callable,
         provider_options: dict | None = None,
-        **encryption_context: str,
-    ):
+        dynamic_mask: bool | None = None,
+        custom_mask: str | None = None,
+        regex_pattern: str | None = None,
+        mask_format: str | None = None,
+        **encryption_context: Any,
+    ) -> Any:
         """
         Helper method to determine whether to apply a given action to the entire input data
         or to specific fields if the 'fields' argument is specified.
@@ -127,8 +224,6 @@ class DataMasking:
             and returns the modified value.
         provider_options : dict
             Provider specific keyword arguments to propagate; used as an escape hatch.
-        encryption_context: str
-            Encryption context to use in encrypt and decrypt operations.
 
         Returns
         -------
@@ -143,11 +238,28 @@ class DataMasking:
                 fields=fields,
                 action=action,
                 provider_options=provider_options,
-                **encryption_context,
+                dynamic_mask=dynamic_mask,
+                custom_mask=custom_mask,
+                regex_pattern=regex_pattern,
+                mask_format=mask_format,
             )
         else:
             logger.debug(f"Running action {action.__name__} with the entire data")
-            return action(data=data, provider_options=provider_options, **encryption_context)
+            if action.__name__ == "erase":
+                return action(
+                    data=data,
+                    provider_options=provider_options,
+                    dynamic_mask=dynamic_mask,
+                    custom_mask=custom_mask,
+                    regex_pattern=regex_pattern,
+                    mask_format=mask_format,
+                )
+            else:
+                return action(
+                    data=data,
+                    provider_options=provider_options,
+                    **encryption_context,
+                )
 
     def _apply_action_to_fields(
         self,
@@ -155,6 +267,10 @@ class DataMasking:
         fields: list,
         action: Callable,
         provider_options: dict | None = None,
+        dynamic_mask: bool | None = None,
+        custom_mask: str | None = None,
+        regex_pattern: str | None = None,
+        mask_format: str | None = None,
         **encryption_context: str,
     ) -> dict | str:
         """
@@ -201,8 +317,10 @@ class DataMasking:
         new_dict = {'a': {'b': {'c': '*****'}}, 'x': {'y': '*****'}}
         ```
         """
+        if not fields:
+            raise ValueError("Fields parameter cannot be empty")
 
-        data_parsed: dict = self._normalize_data_to_parse(fields, data)
+        data_parsed: dict = self._normalize_data_to_parse(data)
 
         # For in-place updates, json_parse accepts a callback function
         # this function must receive 3 args: field_value, fields, field_name
@@ -211,6 +329,10 @@ class DataMasking:
             self._call_action,
             action=action,
             provider_options=provider_options,
+            dynamic_mask=dynamic_mask,
+            custom_mask=custom_mask,
+            regex_pattern=regex_pattern,
+            mask_format=mask_format,
             **encryption_context,  # type: ignore[arg-type]
         )
 
@@ -232,12 +354,6 @@ class DataMasking:
             # For in-place updates, json_parse accepts a callback function
             # that receives 3 args: field_value, fields, field_name
             # We create a partial callback to pre-populate known provider options (action, provider opts, enc ctx)
-            update_callback = functools.partial(
-                self._call_action,
-                action=action,
-                provider_options=provider_options,
-                **encryption_context,  # type: ignore[arg-type]
-            )
 
             json_parse.update(
                 data_parsed,
@@ -246,6 +362,59 @@ class DataMasking:
 
         return data_parsed
 
+    def _apply_masking_rules(self, data: dict, masking_rules: dict) -> dict:
+        """
+        Apply masking rules to data, supporting both simple field names and complex path expressions.
+
+        Args:
+            data: The dictionary containing data to mask
+            masking_rules: Dictionary mapping field names or path expressions to masking rules
+
+        Returns:
+            dict: The masked data dictionary
+        """
+        result = deepcopy(data)
+
+        for path, rule in masking_rules.items():
+            try:
+                jsonpath_expr = parse(f"$.{path}")
+                matches = jsonpath_expr.find(result)
+
+                if not matches:
+                    warnings.warn(f"No matches found for path: {path}", stacklevel=2)
+                    continue
+
+                for match in matches:
+                    try:
+                        value = match.value
+                        if value is not None:
+                            masked_value = self.provider.erase(str(value), **rule)
+                            match.full_path.update(result, masked_value)
+
+                    except Exception as e:
+                        warnings.warn(
+                            f"Error masking value for path {path}: {str(e)}",
+                            category=PowertoolsUserWarning,
+                            stacklevel=2,
+                        )
+                        continue
+
+            except Exception as e:
+                warnings.warn(f"Error processing path {path}: {str(e)}", category=PowertoolsUserWarning, stacklevel=2)
+                continue
+
+        return result
+
+    def _mask_nested_field(self, data: dict, field_path: str, mask_function):
+        keys = field_path.split(".")
+        current = data
+        for key in keys[:-1]:
+            current = current.get(key, {})
+            if not isinstance(current, dict):
+                return
+        if keys[-1] in current:
+            current[keys[-1]] = self.provider.erase(current[keys[-1]], **mask_function)
+
     @staticmethod
     def _call_action(
         field_value: Any,
@@ -253,6 +422,10 @@ class DataMasking:
         field_name: str,
         action: Callable,
         provider_options: dict[str, Any] | None = None,
+        dynamic_mask: bool | None = None,
+        custom_mask: str | None = None,
+        regex_pattern: str | None = None,
+        mask_format: str | None = None,
         **encryption_context,
     ) -> None:
         """
@@ -270,13 +443,18 @@ class DataMasking:
         Returns:
         - fields[field_name]: Returns the processed field value
         """
-        fields[field_name] = action(field_value, provider_options=provider_options, **encryption_context)
+        fields[field_name] = action(
+            field_value,
+            provider_options=provider_options,
+            dynamic_mask=dynamic_mask,
+            custom_mask=custom_mask,
+            regex_pattern=regex_pattern,
+            mask_format=mask_format,
+            **encryption_context,
+        )
         return fields[field_name]
 
-    def _normalize_data_to_parse(self, fields: list, data: str | dict) -> dict:
-        if not fields:
-            raise ValueError("No fields specified.")
-
+    def _normalize_data_to_parse(self, data: str | dict) -> dict:
         if isinstance(data, str):
             # Parse JSON string as dictionary
             data_parsed = self.json_deserializer(data)

aws_lambda_powertools-3.6.1a0/aws_lambda_powertools/utilities/data_masking/provider/base.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import functools
+import json
+import re
+from typing import Any, Callable
+
+from aws_lambda_powertools.utilities.data_masking.constants import DATA_MASKING_STRING
+
+PRESERVE_CHARS = set("-_. ")
+_regex_cache = {}
+
+
+class BaseProvider:
+    """
+    The BaseProvider class serves as an abstract base class for data masking providers.
+
+    Example
+    --------
+    ```python
+    from aws_lambda_powertools.utilities._data_masking.provider import BaseProvider
+    from aws_lambda_powertools.utilities.data_masking import DataMasking
+
+    class MyCustomProvider(BaseProvider):
+        def encrypt(self, data) -> str:
+            # Implementation logic for data encryption
+
+        def decrypt(self, data) -> Any:
+            # Implementation logic for data decryption
+
+        def erase(self, data) -> Any | Iterable:
+            # Implementation logic for data masking
+            pass
+
+    def lambda_handler(event, context):
+        provider = MyCustomProvider(["secret-key"])
+        data_masker = DataMasking(provider=provider)
+
+        data = {
+            "project": "powertools",
+            "sensitive": "password"
+        }
+
+        encrypted = data_masker.encrypt(data)
+
+        return encrypted
+    ```
+    """
+
+    def __init__(
+        self,
+        json_serializer: Callable[..., str] = functools.partial(json.dumps, ensure_ascii=False),
+        json_deserializer: Callable[[str], Any] = json.loads,
+    ) -> None:
+        self.json_serializer = json_serializer
+        self.json_deserializer = json_deserializer
+
+    def encrypt(self, data, provider_options: dict | None = None, **encryption_context: str) -> str:
+        """
+        Abstract method for encrypting data. Subclasses must implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement encrypt()")
+
+    def decrypt(self, data, provider_options: dict | None = None, **encryption_context: str) -> Any:
+        """
+        Abstract method for decrypting data. Subclasses must implement this method.
+        """
+        raise NotImplementedError("Subclasses must implement decrypt()")
+
+    def erase(
+        self,
+        data: Any,
+        dynamic_mask: bool | None = None,
+        custom_mask: str | None = None,
+        regex_pattern: str | None = None,
+        mask_format: str | None = None,
+        masking_rules: dict | None = None,
+        **kwargs,
+    ) -> Any:
+
+        result: Any = DATA_MASKING_STRING
+
+        if not any([dynamic_mask, custom_mask, regex_pattern, mask_format, masking_rules]):
+            if isinstance(data, (str, int, float, dict, bytes)):
+                return DATA_MASKING_STRING
+            elif isinstance(data, (list, tuple, set)):
+                return type(data)([DATA_MASKING_STRING] * len(data))
+            else:
+                return DATA_MASKING_STRING
+
+        if isinstance(data, (str, int, float)):
+            result = self._mask_primitive(str(data), dynamic_mask, custom_mask, regex_pattern, mask_format)
+        elif isinstance(data, dict):
+            result = self._mask_dict(
+                data,
+                dynamic_mask,
+                custom_mask,
+                regex_pattern,
+                mask_format,
+                masking_rules,
+            )
+        elif isinstance(data, (list, tuple, set)):
+            result = self._mask_iterable(
+                data,
+                dynamic_mask,
+                custom_mask,
+                regex_pattern,
+                mask_format,
+                masking_rules,
+            )
+
+        return result
+
+    def _mask_primitive(
+        self,
+        data: str,
+        dynamic_mask: bool | None,
+        custom_mask: str | None,
+        regex_pattern: str | None,
+        mask_format: str | None,
+    ) -> str:
+        if regex_pattern and mask_format:
+            return self._regex_mask(data, regex_pattern, mask_format)
+        elif custom_mask:
+            return self._pattern_mask(data, custom_mask)
+
+        return self._custom_erase(data)
+
+    def _mask_dict(
+        self,
+        data: dict,
+        dynamic_mask: bool | None,
+        custom_mask: str | None,
+        regex_pattern: str | None,
+        mask_format: str | None,
+        masking_rules: dict | None,
+    ) -> dict:
+        return {
+            k: self.erase(
+                v,
+                dynamic_mask=dynamic_mask,
+                custom_mask=custom_mask,
+                regex_pattern=regex_pattern,
+                mask_format=mask_format,
+                masking_rules=masking_rules,
+            )
+            for k, v in data.items()
+        }
+
+    def _mask_iterable(
+        self,
+        data: list | tuple | set,
+        dynamic_mask: bool | None,
+        custom_mask: str | None,
+        regex_pattern: str | None,
+        mask_format: str | None,
+        masking_rules: dict | None,
+    ) -> list | tuple | set:
+        masked_data = [
+            self.erase(
+                item,
+                dynamic_mask=dynamic_mask,
+                custom_mask=custom_mask,
+                regex_pattern=regex_pattern,
+                mask_format=mask_format,
+                masking_rules=masking_rules,
+            )
+            for item in data
+        ]
+        return type(data)(masked_data)
+
+    def _pattern_mask(self, data: str, pattern: str) -> str:
+        """Apply pattern masking to string data."""
+        return pattern[: len(data)] if len(pattern) >= len(data) else pattern
+
+    def _regex_mask(self, data: str, regex_pattern: str, mask_format: str) -> str:
+        """Apply regex masking to string data."""
+        try:
+            if regex_pattern not in _regex_cache:
+                _regex_cache[regex_pattern] = re.compile(regex_pattern)
+            return _regex_cache[regex_pattern].sub(mask_format, data)
+        except re.error:
+            return data
+
+    def _custom_erase(self, data: str) -> str:
+        if not data:
+            return ""
+
+        return "".join("*" if char not in PRESERVE_CHARS else char for char in data)