fix(event-handler): fix ruff lint violations in event_handler module (#8208)

* fix(event-handler): replace Optional[X] and List[X] with X | None and list[X] in openapi/models.py

Replace deprecated typing aliases with modern Python 3.10+ syntax:
- Optional[X] -> X | None
- List[X] -> list[X]
- Dict[X, Y] -> dict[X, Y]
- Set[X] -> set[X]
- Remove unused imports: Dict, List, Optional, Set from typing

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): replace Optional[X] and Dict[X] with modern syntax in swagger_ui/oauth2.py

- Optional[str] -> str | None
- Dict[str, str] -> dict[str, str]
- Remove unused imports: Dict, Optional from typing

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): replace Optional[list] with list | None in graphql_appsync/base.py docstrings

Update docstring code examples to use modern Python 3.10+ syntax:
- Optional[list] -> list | None
- Remove unused `from typing import Optional` from examples

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): fix ruff lint violations in util.py docstrings

Update docstring parameter type hints to use modern Python 3.10+ syntax:
- List[Dict[str, List[str]]] -> list[dict[str, list[str]]]
- Optional[Dict[str, Any]] -> dict[str, Any] | None

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): fix ruff lint violations in appsync.py docstrings

Update docstring parameter type hints to use modern Python 3.10+ syntax:
- Optional[str] -> str | None in field_name parameter descriptions

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): fix ruff lint violations in graphql_appsync/_registry.py docstrings

Update docstring return type hints to use modern Python 3.10+ syntax:
- Optional[Dict] -> dict | None in Returns section

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): fix ruff lint violations in middlewares/openapi_validation.py comments

Update inline comments to use modern Python 3.10+ syntax:
- List[Model] -> list[Model]
- Optional[List[Model]] -> list[Model] | None
- Optional[RootModel[List[Model]]] -> RootModel[list[Model]] | None

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): restore removed comment in OpenAPIExtensions class

Hi @svozza, 
Thank you for catching that! The comment was accidentally 
removed during the refactoring. I have restored it now. Also added the Acknowledgment section to the PR description. Sorry for the oversight! 

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): restore accidentally removed comments in openapi/models.py

fix(event-handler): restore accidentally removed comments in openapi/models.py

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): restore accidentally removed comments in openapi/models.py

Restore all comments that were accidentally removed during the
Optional[X] -> X | None type annotation refactoring in openapi/models.py.

Restored comments include:
- swagger.io specification links before each class definition
  e.g. # https://swagger.io/specification/#contact-object
- JSON Schema 2020-12 reference links and section headers inside Schema class
  e.g. # Ref: JSON Schema 2020-12: https://json-schema.org/...
- MAINTENANCE notes for future Pydantic v1 deprecation
- Inline comments for serialization rules in ParameterBase
  e.g. # Serialization rules for simple scenarios
- "Using Any for Specification Extensions" comments in Operation,
  Components and OpenAPI classes

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): add missing from __future__ import annotations in oauth2.py

Add `from __future__ import annotations` to enable PEP 604 union syntax (X | None) for Python versions below 3.10.

Fixes FA102 ruff lint errors:
- aws_lambda_powertools/event_handler/openapi/swagger_ui/oauth2.py:50

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): revert validator signature to Optional in oauth2.py

Revert client_secret_only_on_dev validator signature from str | None back to Optional[str] to fix FA102 ruff lint error.

PEP 604 union syntax in function signatures requires  `from __future__ import annotations` which conflicts with the existing FA100 noqa suppression in this file.

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

* fix(event-handler): fix UP045 lint error in oauth2.py validator signature

With `from __future__ import annotations` present, ruff UP045 requires `str | None` instead of `Optional[str]` in the validator signature.

- Remove Optional from typing imports
- Convert validator signature to str | None syntax

Part of #8088

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>

---------

Signed-off-by: hirenkumar-n-dholariya <hirenkumarnd@gmail.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>

Author: hirenkumar-n-dholariya

aws_lambda_powertools/event_handler/appsync.py

@@ -392,7 +392,7 @@ def resolver(self, type_name: str = "*", field_name: str | None = None) -> Calla
         ----------
         type_name : str, optional
             GraphQL type e.g., Query, Mutation, by default "*" meaning any
-        field_name : Optional[str], optional
+        field_name : str | None, optional
             GraphQL field e.g., getTodo, createTodo, by default None
 
         Returns
@@ -447,7 +447,7 @@ def batch_resolver(
         ----------
         type_name : str, optional
             GraphQL type e.g., Query, Mutation, by default "*" meaning any
-        field_name : Optional[str], optional
+        field_name : str | None, optional
             GraphQL field e.g., getTodo, createTodo, by default None
         raise_on_error : bool, optional
             Whether to fail entire batch upon error, or handle errors gracefully (None), by default False

aws_lambda_powertools/event_handler/graphql_appsync/_registry.py

@@ -64,7 +64,7 @@ def find_resolver(self, type_name: str, field_name: str) -> dict | None:
             Field name
         Return
         ----------
-        Optional[Dict]
+        dict | None
             A dictionary with the resolver and if raise exception on error
         """
         logger.debug(f"Looking for resolver for type={type_name}, field={field_name}.")

aws_lambda_powertools/event_handler/graphql_appsync/base.py

@@ -25,16 +25,14 @@ def resolver(self, type_name: str = "*", field_name: str | None = None) -> Calla
         Examples
         --------
         ```python
-        from typing import Optional
-
         from aws_lambda_powertools.event_handler import AppSyncResolver
         from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
         from aws_lambda_powertools.utilities.typing import LambdaContext
 
         app = AppSyncResolver()
 
         @app.resolver(type_name="Query", field_name="getPost")
-        def related_posts(event: AppSyncResolverEvent) -> Optional[list]:
+        def related_posts(event: AppSyncResolverEvent) -> list | None:
             return {"success": "ok"}
 
         def lambda_handler(event, context: LambdaContext) -> dict:
@@ -76,16 +74,14 @@ def batch_resolver(
         Examples
         --------
         ```python
-        from typing import Optional
-
         from aws_lambda_powertools.event_handler import AppSyncResolver
         from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
         from aws_lambda_powertools.utilities.typing import LambdaContext
 
         app = AppSyncResolver()
 
         @app.batch_resolver(type_name="Query", field_name="getPost")
-        def related_posts(event: AppSyncResolverEvent, id) -> Optional[list]:
+        def related_posts(event: AppSyncResolverEvent, id) -> list | None:
             return {"post_id": id}
 
         def lambda_handler(event, context: LambdaContext) -> dict:
@@ -127,16 +123,14 @@ def async_batch_resolver(
         Examples
         --------
         ```python
-        from typing import Optional
-
         from aws_lambda_powertools.event_handler import AppSyncResolver
         from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
         from aws_lambda_powertools.utilities.typing import LambdaContext
 
         app = AppSyncResolver()
 
         @app.async_batch_resolver(type_name="Query", field_name="getPost")
-        async def related_posts(event: AppSyncResolverEvent, id) -> Optional[list]:
+        async def related_posts(event: AppSyncResolverEvent, id) -> list | None:
             return {"post_id": id}
 
         def lambda_handler(event, context: LambdaContext) -> dict:

aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -505,11 +505,11 @@ def _is_or_contains_sequence(annotation: Any) -> bool:
 
     This function handles complex type annotations like:
     - List[Model] - direct sequence
-    - Union[Model, List[Model]] - checks if any Union member is a sequence
-    - Optional[List[Model]] - Union[List[Model], None]
-    - RootModel[List[Model]] - checks if the RootModel wraps a sequence
-    - Optional[RootModel[List[Model]]] - Union member that is a RootModel
-    - RootModel[Union[Model, List[Model]]] - RootModel wrapping a Union with a sequence
+    - Union[Model, list[Model]] - checks if any Union member is a sequence
+    - list[Model] | None - Union[list[Model], None]
+    - RootModel[list[Model]] - checks if the RootModel wraps a sequence
+    - RootModel[list[Model]] | None - Union member that is a RootModel
+    - RootModel[Union[Model, list[Model]]] - RootModel wrapping a Union with a sequence
     """
     # Direct sequence check
     if field_annotation_is_sequence(annotation):