perf(parser): eagerly loading all 16 envelopes on import adds ~900ms Lambda cold start latency

[ErezMizrahi]

Expected Behavior

Importing parse or event_parser from aws_lambda_powertools.utilities.parser should not load envelope modules unless an envelope is actually used.

Current Behavior

parser/__init__.py eagerly imports envelopes and BaseEnvelope at module level:

from aws_lambda_powertools.utilities.parser import envelopes
from aws_lambda_powertools.utilities.parser.envelopes import BaseEnvelope

This causes all 16 envelope modules (apigw, sqs, sns, kinesis, dynamodb, cloudwatch, ...) to load on every cold start, even when no envelope is ever used.

Steps to Reproduce

Any Lambda function with:

from aws_lambda_powertools.utilities.parser import parse

Profile with PYTHONPROFILEIMPORTTIME=1 on Lambda and observe:

import time:  30627 |   1413849 | aws_lambda_powertools.utilities.parser
import time:   6263 |    295176 |   aws_lambda_powertools.utilities.parser.envelopes
import time:    989 |    267728 |     aws_lambda_powertools.utilities.parser.envelopes.apigw
import time:    855 |    285029 |     aws_lambda_powertools.utilities.parser.envelopes.apigw  (apigwv2)
# ... 14 more envelope modules

Observed Impact

~900ms added to Lambda INIT_DURATION for every cold start on functions that use parse() without an envelope. Measured on AWS Lambda arm64, Python 3.13, 1024MB.

Possible Solution

Use Python's module-level __getattr__ to defer loading envelopes and BaseEnvelope until they are actually accessed. Public API is fully preserved.

I have submitted PR #8405 with the fix and a regression test.

Environment

• Powertools version: 3.x
• Python version: 3.13
• Lambda runtime: arm64

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[powertools-for-aws-oss-automation]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out our GitHub Discussions: Join the conversation