refactor(typing): reduce aws_lambda_powertools.shared.types usage (#4896

)

* refactor(typing): reduce aws_lambda_powertools.shared.types usage

As discussed in #4607. This simplifies linting and refactoring so we can
introduce

    from __future__ import annotations

to all files, which is the plan as the next step.

* Docmentation fix + small changes

---------

Co-authored-by: Leandro Damascena <[email protected]>

aws_lambda_powertools/event_handler/api_gateway.py

@@ -17,6 +17,7 @@
     Dict,
     Generic,
     List,
+    Literal,
     Mapping,
     Match,
     Optional,
@@ -47,7 +48,6 @@
 from aws_lambda_powertools.shared.cookies import Cookie
 from aws_lambda_powertools.shared.functions import powertools_dev_is_set
 from aws_lambda_powertools.shared.json_encoder import Encoder
-from aws_lambda_powertools.shared.types import Literal
 from aws_lambda_powertools.utilities.data_classes import (
     ALBEvent,
     APIGatewayProxyEvent,

aws_lambda_powertools/event_handler/middlewares/base.py

@@ -1,9 +1,8 @@
 from abc import ABC, abstractmethod
-from typing import Generic
+from typing import Generic, Protocol
 
 from aws_lambda_powertools.event_handler.api_gateway import Response
 from aws_lambda_powertools.event_handler.types import EventHandlerInstance
-from aws_lambda_powertools.shared.types import Protocol
 
 
 class NextMiddleware(Protocol):

aws_lambda_powertools/event_handler/openapi/models.py

@@ -1,14 +1,14 @@
 from enum import Enum
-from typing import Any, Dict, List, Optional, Set, Union
+from typing import Any, Dict, List, Literal, Optional, Set, Union
 
 from pydantic import AnyUrl, BaseModel, Field
+from typing_extensions import Annotated
 
 from aws_lambda_powertools.event_handler.openapi.compat import model_rebuild
 from aws_lambda_powertools.event_handler.openapi.constants import (
     MODEL_CONFIG_ALLOW,
     MODEL_CONFIG_IGNORE,
 )
-from aws_lambda_powertools.shared.types import Annotated, Literal
 
 """
 The code defines Pydantic models for the various OpenAPI objects like OpenAPI, PathItem, Operation, Parameter etc.

aws_lambda_powertools/event_handler/openapi/params.py

@@ -1,9 +1,10 @@
 import inspect
 from enum import Enum
-from typing import Any, Callable, Dict, List, Optional, Tuple, Type, Union
+from typing import Any, Callable, Dict, List, Literal, Optional, Tuple, Type, Union
 
 from pydantic import BaseConfig
 from pydantic.fields import FieldInfo
+from typing_extensions import Annotated, get_args, get_origin
 
 from aws_lambda_powertools.event_handler import Response
 from aws_lambda_powertools.event_handler.openapi.compat import (
@@ -16,7 +17,6 @@
     get_annotation_from_field_info,
 )
 from aws_lambda_powertools.event_handler.openapi.types import CacheKey
-from aws_lambda_powertools.shared.types import Annotated, Literal, get_args, get_origin
 
 """
 This turns the low-level function signature into typed, validated Pydantic models for consumption.

aws_lambda_powertools/event_handler/openapi/types.py

@@ -1,8 +1,8 @@
 import types
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Set, Type, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Set, Type, TypedDict, Union
 
-from aws_lambda_powertools.shared.types import NotRequired, TypedDict
+from typing_extensions import NotRequired
 
 if TYPE_CHECKING:
     from pydantic import BaseModel  # noqa: F401

aws_lambda_powertools/logging/types.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, TypedDict, Union
 
-from aws_lambda_powertools.shared.types import NotRequired, TypeAlias, TypedDict
+from typing_extensions import NotRequired, TypeAlias
 
 LogRecord: TypeAlias = Union[Dict[str, Any], "PowertoolsLogRecord"]
 LogStackTrace: TypeAlias = Union[Dict[str, Any], "PowertoolsStackTrace"]

aws_lambda_powertools/metrics/functions.py

@@ -1,14 +1,14 @@
 from __future__ import annotations
 
 from datetime import datetime
+from typing import List
 
 from aws_lambda_powertools.metrics.provider.cloudwatch_emf.exceptions import (
     MetricResolutionError,
     MetricUnitError,
 )
 from aws_lambda_powertools.metrics.provider.cloudwatch_emf.metric_properties import MetricResolution, MetricUnit
 from aws_lambda_powertools.shared import constants
-from aws_lambda_powertools.shared.types import List
 
 
 def extract_cloudwatch_metric_resolution_value(metric_resolutions: List, resolution: int | MetricResolution) -> int:

aws_lambda_powertools/metrics/provider/cloudwatch_emf/types.py

@@ -1,4 +1,6 @@
-from aws_lambda_powertools.shared.types import List, NotRequired, TypedDict
+from typing import List, TypedDict
+
+from typing_extensions import NotRequired
 
 
 class CloudWatchEMFMetric(TypedDict):

aws_lambda_powertools/metrics/types.py

@@ -1,4 +1,6 @@
-from aws_lambda_powertools.shared.types import NotRequired, TypedDict
+from typing import TypedDict
+
+from typing_extensions import NotRequired
 
 
 class MetricNameUnitResolution(TypedDict):

aws_lambda_powertools/shared/cookies.py

@@ -1,9 +1,7 @@
 from datetime import datetime
 from enum import Enum
 from io import StringIO
-from typing import Optional
-
-from aws_lambda_powertools.shared.types import List
+from typing import List, Optional
 
 
 class SameSite(Enum):

aws_lambda_powertools/shared/types.py

@@ -1,25 +1,3 @@
-import sys
-from typing import Any, Callable, Dict, List, Literal, Protocol, TypedDict, TypeVar, Union
-
-if sys.version_info >= (3, 9):
-    from typing import Annotated
-else:
-    from typing_extensions import Annotated
-
-if sys.version_info >= (3, 11):
-    from typing import NotRequired
-else:
-    from typing_extensions import NotRequired
-
-# Even though `get_args` and `get_origin` were added in Python 3.8, they only handle Annotated correctly on 3.10.
-# So for python < 3.10 we use the backport from typing_extensions.
-if sys.version_info >= (3, 10):
-    from typing import TypeAlias, get_args, get_origin
-else:
-    from typing_extensions import TypeAlias, get_args, get_origin
+from typing import Any, Callable, TypeVar
 
 AnyCallableT = TypeVar("AnyCallableT", bound=Callable[..., Any])  # noqa: VNE001
-# JSON primitives only, mypy doesn't support recursive tho
-JSONType = Union[str, int, float, bool, None, Dict[str, Any], List[Any]]
-
-__all__ = ["get_args", "get_origin", "Annotated", "Protocol", "TypedDict", "Literal", "NotRequired", "TypeAlias"]

aws_lambda_powertools/utilities/batch/types.py

@@ -1,7 +1,5 @@
 import sys
-from typing import Optional, Type, Union
-
-from aws_lambda_powertools.shared.types import List, TypedDict
+from typing import List, Optional, Type, TypedDict, Union
 
 has_pydantic = "pydantic" in sys.modules
 

aws_lambda_powertools/utilities/data_classes/s3_batch_operation_event.py

@@ -1,9 +1,8 @@
 import warnings
 from dataclasses import dataclass, field
-from typing import Any, Dict, Iterator, List, Optional, Tuple
+from typing import Any, Dict, Iterator, List, Literal, Optional, Tuple
 from urllib.parse import unquote_plus
 
-from aws_lambda_powertools.shared.types import Literal
 from aws_lambda_powertools.utilities.data_classes.common import DictWrapper
 
 # list of valid result code. Used both in S3BatchOperationResponse and S3BatchOperationResponseRecord

aws_lambda_powertools/utilities/data_classes/secrets_manager_event.py

@@ -1,4 +1,5 @@
-from aws_lambda_powertools.shared.types import Literal
+from typing import Literal
+
 from aws_lambda_powertools.utilities.data_classes.common import DictWrapper
 
 

aws_lambda_powertools/utilities/feature_flags/__init__.py

@@ -1,10 +1,10 @@
 """Advanced feature flags utility"""
 
-from .appconfig import AppConfigStore
-from .base import StoreProvider
-from .exceptions import ConfigurationStoreError
-from .feature_flags import FeatureFlags
-from .schema import RuleAction, SchemaValidator
+from aws_lambda_powertools.utilities.feature_flags.appconfig import AppConfigStore
+from aws_lambda_powertools.utilities.feature_flags.base import StoreProvider
+from aws_lambda_powertools.utilities.feature_flags.exceptions import ConfigurationStoreError
+from aws_lambda_powertools.utilities.feature_flags.feature_flags import FeatureFlags
+from aws_lambda_powertools.utilities.feature_flags.schema import RuleAction, SchemaValidator
 
 __all__ = [
     "ConfigurationStoreError",

aws_lambda_powertools/utilities/feature_flags/appconfig.py

@@ -4,17 +4,16 @@
 
 from botocore.config import Config
 
+from aws_lambda_powertools.logging import Logger
 from aws_lambda_powertools.utilities import jmespath_utils
+from aws_lambda_powertools.utilities.feature_flags.base import StoreProvider
+from aws_lambda_powertools.utilities.feature_flags.exceptions import ConfigurationStoreError, StoreClientError
 from aws_lambda_powertools.utilities.parameters import (
     AppConfigProvider,
     GetParameterError,
     TransformParameterError,
 )
 
-from ... import Logger
-from .base import StoreProvider
-from .exceptions import ConfigurationStoreError, StoreClientError
-
 
 class AppConfigStore(StoreProvider):
     def __init__(

aws_lambda_powertools/utilities/feature_flags/comparators.py

@@ -5,7 +5,7 @@
 
 from dateutil.tz import gettz
 
-from .schema import HOUR_MIN_SEPARATOR, ModuloRangeValues, TimeValues
+from aws_lambda_powertools.utilities.feature_flags.schema import HOUR_MIN_SEPARATOR, ModuloRangeValues, TimeValues
 
 
 def _get_now_from_timezone(timezone: Optional[tzinfo]) -> datetime:

aws_lambda_powertools/utilities/feature_flags/feature_flags.py

@@ -5,11 +5,10 @@
 
 from typing_extensions import ParamSpec
 
-from ... import Logger
-from ...shared.types import JSONType
-from . import schema
-from .base import StoreProvider
-from .comparators import (
+from aws_lambda_powertools.logging import Logger
+from aws_lambda_powertools.utilities.feature_flags import schema
+from aws_lambda_powertools.utilities.feature_flags.base import StoreProvider
+from aws_lambda_powertools.utilities.feature_flags.comparators import (
     compare_all_in_list,
     compare_any_in_list,
     compare_datetime_range,
@@ -18,7 +17,8 @@
     compare_none_in_list,
     compare_time_range,
 )
-from .exceptions import ConfigurationStoreError
+from aws_lambda_powertools.utilities.feature_flags.exceptions import ConfigurationStoreError
+from aws_lambda_powertools.utilities.feature_flags.types import JSONType
 
 T = TypeVar("T")
 P = ParamSpec("P")

aws_lambda_powertools/utilities/feature_flags/schema.py

@@ -9,9 +9,9 @@
 
 from dateutil import tz
 
-from ... import Logger
-from .base import BaseValidator
-from .exceptions import SchemaValidationError
+from aws_lambda_powertools.logging import Logger
+from aws_lambda_powertools.utilities.feature_flags.base import BaseValidator
+from aws_lambda_powertools.utilities.feature_flags.exceptions import SchemaValidationError
 
 RULES_KEY = "rules"
 FEATURE_DEFAULT_VAL_KEY = "default"

aws_lambda_powertools/utilities/feature_flags/types.py

@@ -0,0 +1,4 @@
+from typing import Any, Dict, List, Union
+
+# JSON primitives only, mypy doesn't support recursive tho
+JSONType = Union[str, int, float, bool, None, Dict[str, Any], List[Any]]

aws_lambda_powertools/utilities/idempotency/hook.py

@@ -1,6 +1,5 @@
-from typing import Any
+from typing import Any, Protocol
 
-from aws_lambda_powertools.shared.types import Protocol
 from aws_lambda_powertools.utilities.idempotency.persistence.datarecord import DataRecord
 
 

aws_lambda_powertools/utilities/idempotency/persistence/redis.py

@@ -5,11 +5,10 @@
 import logging
 from contextlib import contextmanager
 from datetime import timedelta
-from typing import Any, Dict
+from typing import Any, Dict, Literal, Protocol
 
 import redis
 
-from aws_lambda_powertools.shared.types import Literal, Protocol
 from aws_lambda_powertools.utilities.idempotency import BasePersistenceLayer
 from aws_lambda_powertools.utilities.idempotency.exceptions import (
     IdempotencyItemAlreadyExistsError,

aws_lambda_powertools/utilities/parameters/ssm.py

@@ -7,7 +7,7 @@
 import logging
 import os
 import warnings
-from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union, overload
+from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Tuple, Union, overload
 
 import boto3
 from botocore.config import Config
@@ -18,7 +18,6 @@
     resolve_truthy_env_var_choice,
     slice_dictionary,
 )
-from aws_lambda_powertools.shared.types import Literal
 from aws_lambda_powertools.utilities.parameters.base import (
     DEFAULT_MAX_AGE_SECS,
     DEFAULT_PROVIDERS,

aws_lambda_powertools/utilities/parameters/types.py

@@ -1,3 +1,3 @@
-from aws_lambda_powertools.shared.types import Literal
+from typing import Literal
 
 TransformOptions = Literal["json", "binary", "auto", None]

aws_lambda_powertools/utilities/parser/models/cloudwatch.py

@@ -3,12 +3,10 @@
 import logging
 import zlib
 from datetime import datetime
-from typing import Optional, Type, Union
+from typing import List, Optional, Type, Union
 
 from pydantic import BaseModel, Field, field_validator
 
-from aws_lambda_powertools.shared.types import List
-
 logger = logging.getLogger(__name__)
 
 

aws_lambda_powertools/utilities/parser/types.py

@@ -1,11 +1,9 @@
 """Generics and other shared types used across parser"""
 
-from typing import Any, Dict, Type, TypeVar, Union
+from typing import Any, Dict, Literal, Type, TypeVar, Union
 
 from pydantic import BaseModel, Json
 
-from aws_lambda_powertools.shared.types import Literal
-
 Model = TypeVar("Model", bound=BaseModel)
 EnvelopeModel = TypeVar("EnvelopeModel")
 EventParserReturnType = TypeVar("EventParserReturnType")

aws_lambda_powertools/utilities/streaming/s3_object.py

@@ -7,6 +7,7 @@
     Any,
     Iterable,
     List,
+    Literal,
     Optional,
     Sequence,
     TypeVar,
@@ -15,7 +16,6 @@
     overload,
 )
 
-from aws_lambda_powertools.shared.types import Literal
 from aws_lambda_powertools.utilities.streaming._s3_seekable_io import _S3SeekableIO
 from aws_lambda_powertools.utilities.streaming.transformations import (
     CsvTransform,

docs/core/event_handler/api_gateway.md

@@ -380,7 +380,7 @@ In the following example, we use a new `Query` OpenAPI type to add [one out of m
 
 === "validating_query_strings.py"
 
-    ```python hl_lines="8 10 27"
+    ```python hl_lines="8 9 27"
     --8<-- "examples/event_handler_rest/src/validating_query_strings.py"
     ```
 
@@ -418,7 +418,7 @@ Just like we learned in [query string validation](#validating-query-strings), we
 
 For example, we could validate that `<todo_id>` dynamic path should be no greater than three digits.
 
-```python hl_lines="8 10 27" title="validating_path.py"
+```python hl_lines="8 9 27" title="validating_path.py"
 --8<-- "examples/event_handler_rest/src/validating_path.py"
 ```
 
@@ -440,7 +440,7 @@ In the following example, we use a new `Header` OpenAPI type to add [one out of
 
 === "validating_headers.py"
 
-    ```python hl_lines="8 10 27"
+    ```python hl_lines="5 9 27"
     --8<-- "examples/event_handler_rest/src/validating_headers.py"
     ```