Incorrect type annotation for parse function

[DanLipsitt]

The output type specified for aws_lambda_powertools.utilities.parser.parse does not always match the documented or actual output. The output is often a collection but the specified type is a single object.

Expected Behavior

The return type for parse should match the documented output types for each envelope.

Current Behavior

The return type for parse is Model (the type of the model parameter's input) even though the returned value may be a collection with a more complex type such as List[Dict[str, Optional[Model]]].

Possible Solution

There may be a way to solve this using mypy generics but I can't think of how. The return type could be specified manually as something like the following Union of all the possibilities:

Union[Model, List[Optional[Model]], List[Dict[str, Optional[Model]]]]

This would have to be updated as envelopes are added, and it wouldn't cover custom envelopes.

Alternatively, removing the output type annotation from the toplevel parse might allow the type of the underlying envelope's parse function to bubble up.

Steps to Reproduce

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


class Item(BaseModel):
    pass


event: dict = {"Records": []}
result: list[Item] = parse(event=event, model=Item, envelope=envelopes.SnsEnvelope)
print(type(result))

Output:

<class 'list'>

Mypy output:

parser_type_example.py:9: error: Incompatible types in assignment (expression has type "Item", variable has type "List[Item]")
Found 1 error in 1 file (checked 1 source file)

Environment

• Powertools version used:
  1.21.1
• Packaging format (Layers, PyPi):
  Pypi
• AWS Lambda function runtime:
  n/a
• Debugging logs
  n/a

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.

[heitorlessa]

Thanks a lot @DanLipsitt for flagging it.

I confess this has been a flaky area in Parser - we had generics and it half-worked - perhaps an @overload specifically when envelope is set might work.

[heitorlessa]

Looking into this now to see if a quick fix I have in mind can solve, otherwise we'll tackle it for the release after next. Thanks a lot for the sample to reproduce as it helps a ton!

[heitorlessa]

@DanLipsitt got it working - Could you please check this PR to double check this is what you'd expect?

#885

If you can confirm by EOD we can make it into the next release, otherwise, I'll pause this for a while as everything I've tried didn't work (Unions, TypeVar + Type variables, etc.)

Thank you!

[heitorlessa]

Now released as part of 1.23 version