refactor(typing): use PEP 604 syntax for Optional annotations (UP045)

[manshahH]

Issue number: closes #8398

Summary

Clears the first of the four temporary pyupgrade ignores in ruff.toml, following the one rule per PR plan @leandrodamascena outlined in #8047.

Optional[X] becomes X | None across the repository, and "UP045" is removed from lint.ignore so the rule is enforced from here on.

Changes

• 285 violations across 65 files: 24 in aws_lambda_powertools, 25 in examples, 15 in tests, plus ruff.toml
• 283 fixed by the ruff autofix
• 2 converted by hand
• 63 Optional imports left unused by the conversion were removed, since F401 flags them

The two manual cases. Both are in aws_lambda_powertools/utilities/batch/types.py, where Optional[...] sits in a runtime assignment rather than an annotation:

BatchTypeModels = Optional[Union[...]]
BatchSqsTypeModel = Optional[Type[SqsRecordModel]]

Ruff correctly refuses to autofix these, because the expression is evaluated at import time and a rewrite changes the object that actually gets built. I converted them by hand and checked the result against the previous definitions:

Optional[Union[...]] == BatchTypeModels             -> True
Optional[Type[SqsRecordModel]] == BatchSqsTypeModel -> True

Union is deliberately left in place there, since it belongs to UP007. Removing it here would blur the one rule per PR split.

Docstrings. Twenty parameter descriptions and section comments inside files this PR already touches still referred to Optional[...] while the code below them had changed, so they were brought in line. Files not otherwise modified by this PR were left alone.

User experience

No user facing change. This is internal typing syntax only, and the runtime behaviour of every converted annotation and alias is unchanged.

For contributors, UP045 is now enforced, so the older Optional[X] spelling gets caught by make lint instead of being silently accepted.

Verification

• ruff check passes with UP045 enforced
• ruff format --check: 1310 files already formatted
• Full suite excluding e2e: 2497 passed. Six failures are pre existing Windows only path and formatting issues that reproduce identically on a clean develop
• mypy aws_lambda_powertools examples: same error count before and after, no new errors introduced
• bandit security baseline and xenon complexity baseline both unaffected

Happy to carry on with UP007 and then UP035 in the same shape once this one looks right.

Acknowledgment

• This PR meets the Powertools for AWS Lambda (Python) Tenets
• I have read the CONTRIBUTING guide
• I have followed the Code of Conduct

---

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

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.64%. Comparing base (a8df37d) to head (db523a3).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #8399   +/-   ##
========================================
  Coverage    96.64%   96.64%           
========================================
  Files          296      296           
  Lines        14767    14767           
  Branches      1246     1246           
========================================
  Hits         14271    14271           
  Misses         361      361           
  Partials       135      135           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[leandrodamascena]

Thanks for tackling this. I like this direction because it resolves the Ruff issue instead of adding another exception we would need to maintain as technical debt.

I found two small typos that currently fail at import time:

• tests/e2e/utils/data_fetcher/logs.py:57
• tests/e2e/utils/data_fetcher/traces.py:109

Could you please change any | None to:

Any | None

Lowercase any is Python's built-in function, so the current annotation raises a TypeError.

[manshahH]

Good catch, thank you. Fixed in 06b30b6.

Your diagnosis is right. Optional[any] was tolerated because typing never validates its argument, so the lowercase any sat there unnoticed. Once it became any | None the expression is evaluated at import time, and neither module has from __future__ import annotations, so importing them raised:

TypeError: unsupported operand type(s) for |: 'builtin_function_or_method' and 'NoneType'

Both signatures are now Any | None, with Any added to the typing import in logs.py. I also updated the matching docstring line just below the first one, at logs.py:64, which carried the same lowercase any.

This slipped past me because make test runs with --ignore tests/e2e, so these two modules are never imported by the suite. To be sure nothing else of the same shape was hiding in the diff, I walked the AST of all 65 changed files and checked every converted annotation for a left operand that is a builtin function rather than a type. 275 annotations checked, and those were the only two.

All four data_fetcher modules now import cleanly, and ruff check, ruff format --check and the test suite are unchanged.

[leandrodamascena]

Thanks for fixing this and for checking the remaining converted annotations as well. I pulled the latest commit and confirmed that both modules now evaluate the annotations correctly, with Ruff checks also passing.

This fully addresses my review and resolves the Ruff rule without leaving another exception for us to maintain.

Thank you very much for the work. APPROVED!

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[sonarqubecloud]

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 SonarQube Cloud

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!

[powertools-for-aws-oss-automation]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!