fix(parser): overload parse when using envelope

[heitorlessa]

Issue #, if available:

Description of changes:

When using parse function with an envelope, Mypy doesn't allow setting an explicit type as parse returns a Model while an envelope parse could return various types ranging from List[Model], Dict[str, Model], List[Optional[Model], and this can grow over time as more event types are defined too.

This PR uses type function overload to ensure parse continues to return a Model when no envelope is used, and when an envelope is used it'll propagate a generic type allowing an explicit type to be set at runtime.

Gotcha

If you don't set an explicit type when using parse with envelope, Mypy will detect as Any since MyPy can't have a generic return type in this case.

Example

This uses a sample valid SNS payload as per the issue with an empty payload and with non-empty payload.

Mypy output

mypy check.py
check.py:59:13: note: Revealed type is "builtins.list[check.Item]"
check.py:60:13: note: Revealed type is "builtins.list[check.NoItem]"

Python type evaluation

Item list type: <class 'list'>
No item list type: <class 'list'>

from aws_lambda_powertools.utilities.parser import parse, BaseModel, envelopes

from typing import List


class Item(BaseModel):
    message: str


class NoItem(BaseModel):
    ...


payload = {
    "Records": [
        {
            "EventVersion": "1.0",
            "EventSubscriptionArn": "arn:aws:sns:us-east-2:123456789012:sns-lambda",
            "EventSource": "aws:sns",
            "Sns": {
                "SignatureVersion": "1",
                "Timestamp": "2019-01-02T12:45:07.000Z",
                "Signature": "tcc6faL2yUC6dgZdmrwh1Y4cGa/ebXEkAi6RibDsvpi+tE/1+82j...65r==",
                "SigningCertUrl": "https://sns.us-east-2.amazonaws.com/SimpleNotification",
                "MessageId": "95df01b4-ee98-5cb9-9903-4c221d41eb5e",
                "Message": '{"message": "Hello from SNS!"}',
                "Type": "Notification",
                "UnsubscribeUrl": "https://sns.us-east-2.amazonaws.com/?Action=Unsubscribe",
                "TopicArn": "arn:aws:sns:us-east-2:123456789012:sns-lambda",
            },
        }
    ]
}

no_item_payload = {
    "Records": [
        {
            "EventVersion": "1.0",
            "EventSubscriptionArn": "arn:aws:sns:us-east-2:123456789012:sns-lambda",
            "EventSource": "aws:sns",
            "Sns": {
                "SignatureVersion": "1",
                "Timestamp": "2019-01-02T12:45:07.000Z",
                "Signature": "tcc6faL2yUC6dgZdmrwh1Y4cGa/ebXEkAi6RibDsvpi+tE/1+82j...65r==",
                "SigningCertUrl": "https://sns.us-east-2.amazonaws.com/SimpleNotification",
                "MessageId": "95df01b4-ee98-5cb9-9903-4c221d41eb5e",
                "Message": "",
                "Type": "Notification",
                "UnsubscribeUrl": "https://sns.us-east-2.amazonaws.com/?Action=Unsubscribe",
                "TopicArn": "arn:aws:sns:us-east-2:123456789012:sns-lambda",
            },
        }
    ]
}

item_list: List[Item] = parse(model=Item, event=payload, envelope=envelopes.SnsEnvelope)
no_item_list: List[NoItem] = parse(model=NoItem, event=payload, envelope=envelopes.SnsEnvelope)

assert item_list[0].message == "Hello from SNS!"

# reveal_type(item_list)
# reveal_type(no_item_list)

print(f"Item list type: {type(item_list)}")
print(f"No item list type: {type(no_item_list)}")

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.

[codecov-commenter]

Codecov Report

Merging #885 (eefb9e1) into develop (8de3729) will decrease coverage by 0.03%.
The diff coverage is 81.81%.

@@             Coverage Diff             @@
##           develop     #885      +/-   ##
===========================================
- Coverage    99.88%   99.84%   -0.04%     
===========================================
  Files          118      118              
  Lines         5133     5138       +5     
  Branches       573      573              
===========================================
+ Hits          5127     5130       +3     
- Misses           2        4       +2     
  Partials         4        4              

Impacted Files	Coverage Δ
aws_lambda_powertools/utilities/parser/parser.py	93.93% <80.00%> (-6.07%)	⬇️
...mbda_powertools/utilities/parser/envelopes/base.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 8de3729...eefb9e1. Read the comment docs.

[heitorlessa]

will work on addressing test coverage once @DanLipsitt confirms the solution