Change the logic to generate a Literal type annotation to bypass the caching mechanism of typing module

Author: yugokato

src/openapi_test_client/libraries/api/api_functions/utils/param_type.py

@@ -10,12 +10,20 @@
 from common_libs.logging import get_logger
 
 import openapi_test_client.libraries.api.api_functions.utils.param_model as param_model_util
-from openapi_test_client.libraries.api.types import Alias, Constraint, Format, ParamAnnotationType, ParamDef
+from openapi_test_client.libraries.api.types import (
+    Alias,
+    Constraint,
+    Format,
+    ParamAnnotationType,
+    ParamDef,
+    UncacheableLiteralArg,
+)
+from openapi_test_client.libraries.api.types import Optional as Optional_
 from openapi_test_client.libraries.common.constants import BACKSLASH
 from openapi_test_client.libraries.common.misc import dedup
 
 if TYPE_CHECKING:
-    from typing import _AnnotatedAlias  # type: ignore
+    from typing import _AnnotatedAlias, _LiteralGenericAlias  # type: ignore[attr-defined]
 
 
 logger = get_logger(__name__)
@@ -161,7 +169,7 @@ def resolve(param_type: str, param_format: str | None = None) -> Any:
         )
     else:
         if enum := param_def.get("enum"):
-            type_annotation = Literal[*enum]
+            type_annotation = generate_literal_type(*enum)
         elif isinstance(param_def, ParamDef.UnknownType):
             logger.warning(
                 f"Param '{param_name}': Unable to locate a parameter type in the following parameter object. "
@@ -248,11 +256,11 @@ def replace_base_type(tp: Any, new_type: Any, replace_container_type: bool = Fal
         args = get_args(tp)
         if is_union_type(tp):
             if is_optional_type(tp):
-                return Optional[replace_base_type(args[0], new_type)]  # noqa: UP007
+                return generate_optional_type(replace_base_type(args[0], new_type))
             else:
                 return replace_base_type(args, new_type)
         elif origin_type is Annotated:
-            return Annotated[replace_base_type(tp.__origin__, new_type), *tp.__metadata__]
+            return annotate_type(replace_base_type(tp.__origin__, new_type), *tp.__metadata__)
         elif origin_type in [list, tuple]:
             if replace_container_type:
                 return new_type
@@ -290,7 +298,7 @@ def is_type_of(param_type: str | Any, type_to_check: Any) -> bool:
             # Add if needed
             raise NotImplementedError
     elif origin_type := get_origin(param_type):
-        if origin_type is type_to_check:
+        if (origin_type is type_to_check) or (origin_type is Union and type_to_check in [Optional, Optional_]):
             return True
         elif origin_type is Annotated:
             return is_type_of(param_type.__origin__, type_to_check)
@@ -345,23 +353,23 @@ def generate_union_type(type_annotations: Sequence[Any]) -> Any:
 
 
 def generate_optional_type(tp: Any) -> Any:
-    """Convert the type annotation to Optional[tp]
-
-    Wrap the type with `Optional[]`, but using `Union` with None instead as there seems to be a cache issue
-    where `Optional[Literal['val1', 'val2']]` with change the order of Literal parameters due to the cache.
-
-    eg. The issue seen in Python 3.11
-    >>> t1 = Literal["foo", "bar"]
-    >>> Optional[t1]
-    typing.Optional[typing.Literal['foo', 'bar']]
-    >>> t2 = Literal["bar", "foo"]
-    >>> Optional[t2]
-    typing.Optional[typing.Literal['foo', 'bar']]  <--- HERE
-    """
+    """Convert the type annotation to Optional[tp]"""
     if is_optional_type(tp):
         return tp
     else:
-        return Union[tp, None]  # noqa: UP007
+        return Optional[tp]  # noqa: UP007
+
+
+def generate_literal_type(*args: Any, uncacheable: bool = True) -> _LiteralGenericAlias:
+    """Generate a Literal type annotation using given args
+
+    :param args: Literal args
+    :param uncacheable: Make this Literal type uncacheable
+    """
+    if uncacheable:
+        cacheable_args = tuple(arg.obj if isinstance(arg, UncacheableLiteralArg) else arg for arg in args)
+        args = tuple(UncacheableLiteralArg(arg) for arg in dedup(*cacheable_args))
+    return Literal[*args]
 
 
 def annotate_type(tp: Any, *metadata: Any) -> Any:
@@ -378,7 +386,7 @@ def annotate_type(tp: Any, *metadata: Any) -> Any:
         return modify_annotated_metadata(tp, *metadata, action="add")
     elif is_optional_type(tp):
         inner_type = generate_union_type([x for x in get_args(tp) if x is not NoneType])
-        return Optional[annotate_type(inner_type, *metadata)]  # noqa: UP007
+        return generate_optional_type(annotate_type(inner_type, *metadata))
     else:
         return Annotated[tp, *metadata]
 
@@ -411,7 +419,7 @@ def modify_metadata(tp: Any) -> Any:
                     raise ValueError("At least one metadata must exist after the action is performed")
             else:
                 new_metadata = dedup(*metadata)
-            return Annotated[get_args(tp)[0], *new_metadata]
+            return annotate_type(get_args(tp)[0], *new_metadata)
         else:
             if is_union_type(tp):
                 return generate_union_type([modify_metadata(arg) for arg in get_args(tp)])
@@ -478,7 +486,7 @@ def merge_args_per_origin(args: Sequence[Any]) -> tuple[Any, ...]:
             # stop using set here
             combined_args = dedup(*args1, *args2)
             if origin is Literal:
-                return Literal[*combined_args]
+                return generate_literal_type(*combined_args)
             elif origin is Annotated:
                 # If two Annotated types have different set of ParamAnnotationType objects in metadata, treat them as
                 # different types as a union type. Otherwise merge them
@@ -492,7 +500,7 @@ def merge_args_per_origin(args: Sequence[Any]) -> tuple[Any, ...]:
                 ) or not (annotation_types1 or annotation_types2):
                     combined_type = merge_annotation_types(get_args(tp1)[0], get_args(tp2)[0])
                     combined_metadata = dedup(*tp1.__metadata__, *tp2.__metadata__)
-                    return Annotated[combined_type, *combined_metadata]
+                    return annotate_type(combined_type, *combined_metadata)
                 else:
                     return generate_union_type([tp1, tp2])
             elif origin is dict:
@@ -509,7 +517,7 @@ def merge_args_per_origin(args: Sequence[Any]) -> tuple[Any, ...]:
             elif origin is list:
                 return list[generate_union_type(merge_args_per_origin(combined_args))]
             elif origin in [Union, UnionType]:
-                return Union[*merge_args_per_origin(combined_args)]
+                return generate_union_type(merge_args_per_origin(combined_args))
 
         # TODO: Needs improvements to cover more cases
         if is_optional_type(tp1):

src/openapi_test_client/libraries/api/types.py

@@ -485,3 +485,47 @@ class Constraint(ParamAnnotationType):
     #       but Pydantic currently treats them as an integer
     exclusive_minimum: int | None = None
     exclusive_maximum: int | None = None
+
+
+class UncacheableLiteralArg:
+    """Make args for typing.Literal uncacheable
+
+    Due to the default cache mechanism implemented in the typing module, the order of arguments for the generated
+    Literal type annotation can be unexpected if there's a cache. This behavior causes our dynamic code generation
+    unstable if API specs define more than one param objects that have the exact same enum values but in different
+    orders. Wrapping each Literal arg value with this class ensures the cached behavior will not happen during the code
+    generation.
+
+    eg.
+    1. The default behavior of typing module with cache
+    >>> from typing import Literal, Optional
+    >>> t1 = Literal["foo", "bar"]
+    >>> Optional[t1]
+    typing.Optional[typing.Literal['foo', 'bar']]
+    >>> t2 = Literal["bar", "foo"]
+    >>> Optional[t2]
+    typing.Optional[typing.Literal['foo', 'bar']]   <--- HERE (Unexpected order due to the cached result)
+
+    2. Uncached behavior
+    >>> t1 = Literal[UncacheableLiteralArg("foo"), UncacheableLiteralArg("bar")]
+    >>> Optional[t1]
+    typing.Optional[typing.Literal['foo', 'bar']]
+    >>> t2 = Literal[UncacheableLiteralArg("bar"), UncacheableLiteralArg("foo")]
+    >>> Optional[t2]
+    typing.Optional[typing.Literal['bar', 'foo']]   <--- HERE (Expected order)
+    """
+
+    def __init__(self, obj: Any):
+        self.obj = obj
+
+    def __repr__(self) -> str:
+        return repr(self.obj)
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, UncacheableLiteralArg):
+            return self.obj == other.obj
+        else:
+            return self.obj == other
+
+    def __hash__(self) -> int:
+        return id(self)

tests/integration/conftest.py

@@ -149,5 +149,5 @@ def temp_app_client(
 
 
 @pytest.fixture(autouse=True)
-def _steram_cmd_output(request: FixtureRequest):
+def _steram_cmd_output(request: FixtureRequest) -> None:
     os.environ["IS_CAPTURING_OUTPUT"] = str(request.config.option.capture != "no").lower()

tests/unit/test_param_type.py

@@ -6,7 +6,15 @@
 import pytest
 
 import openapi_test_client.libraries.api.api_functions.utils.param_type as param_type_util
-from openapi_test_client.libraries.api.types import Alias, Constraint, Format, Optional, ParamModel, Unset
+from openapi_test_client.libraries.api.types import (
+    Alias,
+    Constraint,
+    Format,
+    Optional,
+    ParamModel,
+    UncacheableLiteralArg,
+    Unset,
+)
 
 
 class MyClass: ...
@@ -37,7 +45,9 @@ class MyParamModel(ParamModel):
         (dict, "dict"),
         (dict[str, Any], "dict[str, Any]"),
         (Literal[None], "Literal[None]"),
+        (Literal[UncacheableLiteralArg(None)], "Literal[None]"),
         (Literal["1", "2"], "Literal['1', '2']"),
+        (Literal[UncacheableLiteralArg("1"), UncacheableLiteralArg("2")], "Literal['1', '2']"),
         (MyClass, MyClass.__name__),
         (MyParamModel, MyParamModel.__name__),
         (ForwardRef(MyParamModel.__name__), MyParamModel.__name__),
@@ -182,6 +192,9 @@ def test_replace_baser_type(tp: Any, replace_with: Any, expected_type: Any) -> N
         (list[str], str, False),
         (Annotated[list[str], "meta"], str, False),
         (Optional[Annotated[list[str], "meta"]], str, False),
+        (Optional[Annotated[Literal[1], "meta"]], Optional, True),
+        (Optional[Annotated[Literal[1], "meta"]], Annotated, True),
+        (Optional[Annotated[Literal[1], "meta"]], Literal, True),
     ],
 )
 def test_is_type_of(param_type: Any, type_to_check: Any, is_type_of: bool) -> None:
@@ -293,6 +306,24 @@ def test_generate_optional_type(tp: Any, expected_type: Any) -> None:
     assert param_type_util.generate_optional_type(tp) == expected_type
 
 
+@pytest.mark.parametrize("uncacheable", [True, False])
+def test_generate_literal_type(uncacheable: bool) -> None:
+    """Verify that a literal type annotation can be generated with/without the typing module's caching mechanism"""
+    args1 = ["1", "2", "2", "3"]
+    args2 = ["3", "2", "1", "2"]
+    tp1 = param_type_util.generate_literal_type(*args1, uncacheable=uncacheable)
+    tp2 = param_type_util.generate_literal_type(*args2, uncacheable=uncacheable)
+    if uncacheable:
+        assert tp1 != tp2
+        assert repr(Optional[tp1]) == "typing.Optional[typing.Literal['1', '2', '3']]"
+        assert repr(Optional[tp2]) == "typing.Optional[typing.Literal['3', '2', '1']]"
+    else:
+        # NOTE: This is the default behavior of typing.Literal
+        assert Literal[*args1] == tp1 == tp2
+        assert repr(Optional[tp1]) == "typing.Optional[typing.Literal['1', '2', '3']]"
+        assert repr(Optional[tp2]) == "typing.Optional[typing.Literal['1', '2', '3']]"
+
+
 @pytest.mark.parametrize(
     ("tp", "metadata", "expected_type"),
     [
@@ -451,7 +482,11 @@ def test_get_annotated_type(tp: Any, annotated_type: Any) -> None:
 )
 def test_merge_annotation_types(tp1: Any, tp2: Any, expected_type: Any) -> None:
     """Verify that two annotation types acn be merged"""
-    assert param_type_util.merge_annotation_types(tp1, tp2) == expected_type
+    if get_origin(tp1) is Literal or get_origin(tp2) is Literal:
+        assert param_type_util.merge_annotation_types(tp1, tp2) != expected_type
+        assert repr(param_type_util.merge_annotation_types(tp1, tp2)) == repr(expected_type)
+    else:
+        assert param_type_util.merge_annotation_types(tp1, tp2) == expected_type
 
 
 @pytest.mark.parametrize(