feat: expose jmespath powertools functions

[heitorlessa]

Issue #, if available: #661

Description of changes:

This exposes an internal utility in Lambda Powertools to extract and deserialize JSON data using JMESPath w/ custom functions.

This will allow customers to a) reduce their boilerplate in extracting and decoding portions of their JSON objects, b) quickly extract JSON objects from popular event sources without resorting to documentation, and c) bring their own deserializers to recursively and conditionally decode data in any format.

from aws_lambda_powertools.utilities.jmespath_utils import extract_data_from_envelope

from aws_lambda_powertools.utilities.typing import LambdaContext


def handler(event: dict, context: LambdaContext):
    payload = extract_data_from_envelope(data=event, envelope="powertools_json(body)")
    customer = payload.get("customerId")  # now deserialized
    ...

Bring Your Own Custom JMESPath functions

from aws_lambda_powertools.utilities.jmespath_utils import (
    PowertoolsFunctions, extract_data_from_envelope)
from jmespath.functions import signature


class CustomFunctions(PowertoolsFunctions):
    @signature({'types': ['string']})  # Only decode if value is a string
    def _func_special_decoder(self, s):
        return my_custom_decoder_logic(s)

custom_jmespath_options = {"custom_functions": CustomFunctions()}

def handler(event, context):
    # use the custom name after `_func_`
    extract_data_from_envelope(data=event,
                               envelope="special_decoder(body)",
                               jmespath_options=**custom_jmespath_options)
    ...

Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics

Breaking change checklist

RFC issue #:

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

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

---

View rendered docs/utilities/idempotency.md
View rendered docs/utilities/jmespath_functions.md

[codecov-commenter]

Codecov Report

Merging #736 (348aee2) into develop (dec3c88) will decrease coverage by 0.16%.
The diff coverage is 33.33%.

@@             Coverage Diff             @@
##           develop     #736      +/-   ##
===========================================
- Coverage    99.93%   99.77%   -0.17%     
===========================================
  Files          116      117       +1     
  Lines         4914     4922       +8     
  Branches       271      271              
===========================================
  Hits          4911     4911              
- Misses           1        9       +8     
  Partials         2        2              

Impacted Files	Coverage Δ
aws_lambda_powertools/logging/logger.py	98.43% <ø> (ø)
...a_powertools/utilities/jmespath_utils/envelopes.py	0.00% <0.00%> (ø)
...da_powertools/utilities/feature_flags/appconfig.py	100.00% <100.00%> (ø)
...wertools/utilities/idempotency/persistence/base.py	99.36% <100.00%> (ø)
...da_powertools/utilities/jmespath_utils/__init__.py	100.00% <100.00%> (ø)
...ambda_powertools/utilities/validation/validator.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update dec3c88...348aee2. Read the comment docs.