refactor(examples): add from __future__ import annotations

[ericbn]

Issue number: #4607

Summary

Changes

Add from __future__ import annotations to all examples

User experience

Discussed in #4607

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• [X] Meet tenets criteria
• [X] I have performed a self-review of this change
• [X] Changes have been tested
• [ ] Changes are documented
• [X] PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• [ ] Migration process documented
• [ ] Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarqubecloud[bot]]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[ericbn]

@leandrodamascena for you to have a glimpse on how all the examples changes look like and assess if it's worth it. Most changes here have been automatically done and deserve manual review. Two pending changes to this PR are:

1. removing the from __future__ import annotations from files where no other change is required
2. updating markdown annotations

[ericbn]

❯ git show | grep '\-from typing import' | wc -l
      95

❯ git show | grep '\+from typing import .*TYPE_CHECKING' | wc -l
     292

We're arguably adding much more from typing import TYPE_CHECKING than removing or updating existing from typing import (anything).

[github-actions[bot]]

No related issues found. Please ensure there is an open issue related to this change to avoid significant delays or closure.

[leandrodamascena]

@leandrodamascena for you to have a glimpse on how all the examples changes look like and assess if it's worth it. Most changes here have been automatically done and deserve manual review. Two pending changes to this PR are:

1. removing the from __future__ import annotations from files where no other change is required
2. updating markdown annotations

Hi @ericbn! Sorry for the delay in responding, I had some time off today.

I'm more than happy to move forward with this PR and refactor our example to make it more pythonic. I was reading something expected for Python 3.13 and 3.14 and came across PEP 649 which seems to replace __future__ annotations in the future, but is only expected for Python 3.14.

The only thing that concerns me is the amount of examples we are changing and the possible side effect we are creating in our documentation because we will need to manually change all the highlights. Our documentation is widely used not only by those who are getting their first contact with Powertools, but also by those who are looking for some very specific examples. We know of customers who even use some examples as the base of their production code.

Changing the examples and fixing all the highlights to align with our objectives is a manual task that will take some time. Additionally, we may still make small mistakes during this process. And having a documentation that includes issues in the highlights could make the experience less engaging for our users.

We opened an issue in the Material for Mkdocs project so we could highlight using comments in the python file, but there are some challenges implementing this in other projects that Material Mkdocs uses as dependency, so we haven't been able to automate this yet.

So I would like to agree with you on the following steps:

1 - Pause this PR for now. 2 - Focus our efforts at this time on the PRs that are open for the codebase. 3 - We will release V3 in August/early September. 4 - Return to this PR and divide it into several other PRs. We can divide the efforts so that this is not extremely tiring for you.

What do you think about?

[ericbn]

Oi @leandrodamascena. Totally agree with all your points! Also very good to know the challenges around highlighting.

[leandrodamascena]

Hi @ericbn! This PR is very old and can't be merged because of the conflicts and branch differences! What I'm going to do now to restart the work here:

1 - I'm closing this PR as unplanned 2 - I'll open a series of issues next week to rebuild our examples and adopt Python best practices by adding __future__ annotations 3 - I'll let you know to collaborate on this work if you have the bandwidth.

Thanks again for this idea, this is really a great improvement to our documentation.

[ericbn]

Oi @leandrodamascena. Sure, I'll be very happy to be able to contribute again!