Bug: SQSEnvelope return type not compatible with parse

[Mavtti]

Expected Behaviour

No mypy error when using from aws_lambda_powertools.utilities.parser import parse function with SQSEnveloppe.
Since SQS payload returns a list of events, the return type could be a list of my model.

Current Behaviour

Mypy returns an error since there's no overload for the function from aws_lambda_powertools.utilities.parser import parse where the return type is List[T].
I've to use type: ignore

Code snippet

my_events: list[MyClass] = parse(
            events, model=MyClass, envelope=envelopes.SqsEnvelope  # type: ignore
        )

Possible Solution

Add overload with return type List[T] for function parse

Steps to Reproduce

Use parse function with a pydantic model and SQSEnveloppe.
Run mypy

Powertools for AWS Lambda (Python) version

latest

AWS Lambda function runtime

3.9

Packaging format used

PyPi

Debugging logs

Thanks for the repo, it's great !

[leandrodamascena]

Hi @Mavtti! Thanks a lot for reporting this issue with type checking! We know we have some issues using strict typing with mypy/pyright, but most of them are because we depend on some third-party library that we can't enforce strict type checking on, so that's why we don't support strict typing in Powertools.

On the other hand, I know this is super important for a better developer experience and I'm happy to try to improve type annotation with parser/envelope.

I'll need to do some investigation because the issue is not only with the parse signature itself, but since you're using envelope, we need to call this function and this is possibly the source of the issue.

If you have any ideas on how to fix this, please send a PR and I'll be more than happy to review it as soon as possible! And thanks for the kind words about the project, we really love it when customers are happy using Powertools.

[Mavtti]

From my understanding:

def parse(event: dict[str, Any], model: type[T], envelope: type[Envelope] | None = None):
    if envelope and callable(envelope):
        try:
            logger.debug(f"Parsing and validating event model with envelope={envelope}")
            return envelope().parse(data=event, model=model)

since it directly returns SQSEnveloppe.parse, it should accept its return type.
I've tested locally and simply adding:

@overload
def parse(event: dict[str, Any], model: type[T], envelope: type[Envelope]) -> list[T]: ...  # pragma: no cover

Should do the trick.

I've never tried to contribute, will check how to do it.

[leandrodamascena]

Yes, that was my first thought, but this is not working as expected in my environment. Is it working in yours?