Added docstrings to baseprovider

Author: seshubaws

aws_lambda_powertools/utilities/_data_masking/base.py

@@ -37,7 +37,7 @@ def lambda_handler(event, context):
 
  data = {
  "project": "powertools",
- "sensitive": "xxxxxxxxxx"
+ "sensitive": "password"
  }
 
  masked = masker.mask(data,fields=["sensitive"])

aws_lambda_powertools/utilities/_data_masking/exceptions.py

@@ -24,5 +24,5 @@ class DataMaskingDecryptValueError(Exception):
 
 class DataMaskingContextMismatchError(Exception):
  """
- Decrypting an invalid field.
+ Decrypting with the incorrect encryption context.
  """

aws_lambda_powertools/utilities/_data_masking/provider/base.py

@@ -6,8 +6,63 @@
 
 class BaseProvider:
  """
- When you try to create an instance of a subclass that does not implement the encrypt method,
- you will get a NotImplementedError with a message that says the method is not implemented:
+ The BaseProvider class serves as an abstract base class for data masking providers.
+
+ Attributes
+ ----------
+ json_serializer : Callable
+ A callable function responsible for JSON serialization.
+ json_deserializer : Callable
+ A callable function responsible for JSON deserialization.
+
+ Methods
+ -------
+ default_json_serializer(data)
+ Default method for JSON serialization.
+ default_json_deserializer(data)
+ Default method for JSON deserialization.
+ encrypt(data)
+ Abstract method for encrypting data. Subclasses must implement this method.
+ decrypt(data)
+ Abstract method for decrypting data. Subclasses must implement this method.
+ mask(data)
+ Default method for masking data.
+
+ Examples
+ --------
+ ```
+ 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 mask(self, data) -> Union[str, 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, fields=["sensitive"])
+
+ return encrypted
+ ```
+
+ Raises
+ -------
+ NotImplementedError
+ If `encrypt()` or `decrypt()` methods are not implemented.
  """
 
  def __init__(self, json_serializer=None, json_deserializer=None) -> None:
@@ -27,6 +82,16 @@ def decrypt(self, data) -> Any:
  raise NotImplementedError("Subclasses must implement decrypt()")
 
  def mask(self, data) -> Union[str, Iterable]:
+ """
+ This method irreversibly masks data. 
+ 
+ If the data to be masked is of type `str`, `dict`, or `bytes`,
+ this method will return a masked string, i.e. "*****".
+
+ If the data to be masked is of an iterable type like `list`, `tuple`, 
+ or `set`, this method will return a new object of the same type as the 
+ input data but with each element replaced by the string "*****".
+ """
  if isinstance(data, (str, dict, bytes)):
  return DATA_MASKING_STRING
  elif isinstance(data, (list, tuple, set)):

aws_lambda_powertools/utilities/_data_masking/provider/kms/aws_encryption_sdk.py

@@ -50,16 +50,16 @@ class AwsEncryptionSdkProvider(BaseProvider):
 
  def lambda_handler(event, context):
  provider = AwsEncryptionSdkProvider(["arn:aws:kms:us-east-1:0123456789012:key/key-id"])
- masker = DataMasking(provider=provider)
+ data_masker = DataMasking(provider=provider)
 
  data = {
  "project": "powertools",
- "sensitive": "xxxxxxxxxx"
+ "sensitive": "password"
  }
 
- masked = masker.encrypt(data,fields=["sensitive"])
+ encrypted = data_masker.encrypt(data, fields=["sensitive"])
 
- return masked
+ return encrypted
 
  ```
  """