Feat/masking input types support

[VatsalGoel3]

Issue number: #3473

Summary

Changes

This PR adds support to the DataMasking utility to handle complex Python input types such as:

• Pydantic models
• Dataclasses
• Standard Python classes with .dict() method

To support this, a new prepare_data function was introduced, which performs type introspection and converts the input data into a dictionary before processing.

This function is now invoked at the beginning of the erase, encrypt, and decrypt methods, allowing these methods to seamlessly accept structured objects in addition to primitive types like dict, str, list, etc.

User experience

Before:

from aws_lambda_powertools.utilities.data_masking import DataMasking
from pydantic import BaseModel

class MyModel(BaseModel):
    name: str
    age: int

data = MyModel(name="powertools", age=5)
masker = DataMasking()
masked = masker.erase(data, fields=["age"])  # ❌ This raised errors or did not work

After:

# ✅ Now works correctly and returns: {'name': 'powertools', 'age': '*****'}
masked = masker.erase(data, fields=["age"])

This allows customers to use the utility directly with modern application architectures that use type-safe data structures.

Checklist

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number: N/A

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[VatsalGoel3]

@leandrodamascena, for now I applied the prepare_data() function as you suggested in the Issue, but I have an idea for making the function more robust and covering more edge cases, it would be like

"""
Recursively convert complex objects into dictionaries (or simple types) so that they can be
processed by the data masking utility. This function handles:

- Dataclasses (using dataclasses.asdict)
- Pydantic models (using model_dump)
- Custom classes with a dict() method
- Fallback to using __dict__ if available
- Recursively traverses dicts, lists, tuples, and sets
- Guards against circular references

Parameters
----------
data : Any
    The input data which may be a complex type.
_visited : set, optional
    Internal set of visited object IDs to prevent infinite recursion on cyclic references.

Returns
-------
Any
    A primitive type, or a recursively converted structure (dict, list, etc.)
"""

If that is more relevant, will implement this one.