refactor(jmespath_utils): deprecate extract_data_from_envelope in favor of query

[n-k1]

Issue number: #4218

Summary

Changes

• Added a query method in jmespath_utils/__init__.py with the same implementation as extract_data_from_envelope
• Added a warning to extract_data_from_envelope and updated docstring

User experience

extract_data_from_envelope will continue to work with a deprecation warning and will be removed in the next major version. query will replace extract_data_from_envelope.

from aws_lambda_powertools.utilities.jmespath_utils import query
from aws_lambda_powertools.utilities.typing import LambdaContext


def handler(event: dict, context: LambdaContext) -> dict:
    payload = query(data=event, envelope="powertools_json(body)")
    customer_id = payload.get("customerId")  # now deserialized

    # also works for fetching and flattening deeply nested data
    some_data = query(data=event, envelope="deeply_nested[*].some_data[]")

    return {"customer_id": customer_id, "message": "success", "context": some_data, "statusCode": 200}

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• 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?

This is not a breaking change. extract_data_from_envelope will continue to work with a deprecation warning and will only be removed in the next major version.

RFC issue number:

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 SonarCloud

[leandrodamascena]

Hi @n-k1! Thank you so much for taking the time to make this PR and having attention to details. I made a small change to it by adding a decorator to say that the method was deprecated and I changed the exception type.

This will be included in our major version v3!!

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!