Docs: Depends import gotcha

[Dilski]

What were you searching in the docs?

Absolutely loving that new Depends in the REST API handler, massive improvement to how we've done things.

Something we've noticed is when testing with dependency overrides, the imports for the dependency function have to match exactly between the test file and the handler file.

For example doing dependency overrides with get_config in a test with imports like this (despite it being the same actual function) means the override won't be applied and will instead resolve the actual get_config.

# in handler.py
from depends import get_config

# in test_handler.py
from my_app.api_handler.depends import get_config

what you need to do would be

# in handler.py
from depends import get_config

# in test_handler.py
from depends import get_config

This is a funky gotcha that's not immediately obvious or debuggable, so a note in the docs could be helpful.

Is this related to an existing documentation section?

https://docs.aws.amazon.com/powertools/python/latest/core/event_handler/api_gateway/#testing-with-dependency-overrides

How can we improve?

I think having a call-out about this gotcha could be helpful in the testing section.

Got a suggestion in mind?

When using dependency_overrides, the imported dependency reference in your test must exactly match the one used by the handler. (With sensible example, like what I've provided)

Acknowledgment

• I understand the final update might be different from my proposed suggestion, or refused.

[leandrodamascena]

Hey @Dilski, thanks for opening this!

Really glad to hear you're enjoying the Depends feature. And yeah, this is a sneaky gotcha, the import path has to match exactly because Python treats them as different objects in sys.modules otherwise.

A callout in the docs would definitely help others avoid this. Would you be up for sending a PR?

Let me know if you need any help!

[hirenkumar-n-dholariya]

Hey @leandrodamascena, I have raised a PR to address this change - #8269

Added a ???+ warning callout in the "Testing with dependency overrides" section with ✅/❌ tabbed examples explaining that the import path for dependency_overrides must exactly match between the handler and test file.

Happy to iterate if anything needs adjusting! Please review and kindly do the needful.

[powertools-for-aws-oss-automation]

Warning

This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.