fix(typing): use typing extensions package on python versions under 3.11

Author: tharropoulos

src/typesense/api_call.py

@@ -1,17 +1,10 @@
+
+from __future__ import annotations
+
 import copy
 import json
+import sys
 import time
-from typing import (
-    Any,
-    Callable,
-    Generic,
-    Literal,
-    NotRequired,
-    TypedDict,
-    TypeVar,
-    Unpack,
-    overload,
-)
 
 import requests
 from .exceptions import (HTTPStatus0Error, ObjectAlreadyExists,
@@ -21,20 +14,34 @@
 from typesense.configuration import Configuration, Node
 from .logger import logger
 session = requests.session()
-TParams = TypeVar('TParams', bound=dict[str, Any])
-TBody = TypeVar('TBody', bound=dict[str, Any])
-TEntityDict = TypeVar('TEntityDict')
-
 
-class SessionFunctionKwargs(Generic[TParams, TBody], TypedDict):
-    params: NotRequired[TParams | None]
-    data: NotRequired[TBody | str]
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+TParams = typing.TypeVar("TParams", bound=typing.Dict[str, typing.Any])
+TBody = typing.TypeVar("TBody", bound=typing.Dict[str, typing.Any])
+TEntityDict = typing.TypeVar("TEntityDict")
+class SessionFunctionKwargs(typing.Generic[TParams, TBody], typing.TypedDict):
+    """
+    Dictionary of keyword arguments for the session function.
+
+    Attributes:
+        params (TParams | None): The request parameters.
+        data (TBody | str): The request body.
+        timeout (float): The timeout for the request.
+        verify (bool): Whether to verify
+    """
+
+    params: typing.NotRequired[TParams | None]
+    data: typing.NotRequired[TBody | str]
     timeout: float
     verify: bool
 
 
-class ApiCall(Generic[TEntityDict, TParams, TBody]):
     API_KEY_HEADER_NAME = 'X-TYPESENSE-API-KEY'
+class ApiCall(typing.Generic[TEntityDict, TParams, TBody]):
 
     def __init__(self, config: Configuration):
         self.config = config
@@ -103,31 +110,31 @@ def get_exception(http_code: int) -> type[TypesenseClientError]:
         else:
             return TypesenseClientError
 
-    @overload
+    @typing.overload
     def make_request(
         self,
-        fn: Callable[..., requests.models.Response],
+        fn: typing.Callable[..., requests.models.Response],
         endpoint: str,
-        as_json: Literal[True],
-        **kwargs: Unpack[SessionFunctionKwargs[TParams, TBody]],
-    ) -> TEntityDict: ...
+        as_json: typing.Literal[True],
+        **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]],
+    ) -> TEntityDict:
 
-    @overload
+    @typing.overload
     def make_request(
         self,
-        fn: Callable[..., requests.models.Response],
+        fn: typing.Callable[..., requests.models.Response],
         endpoint: str,
-        as_json: Literal[False],
-        **kwargs: Unpack[SessionFunctionKwargs[TParams, TBody]],
-    ) -> str: ...
+        as_json: typing.Literal[False],
+        **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]],
+    ) -> str:
 
     # Makes the actual http request, along with retries
     def make_request(
         self,
-        fn: Callable[..., requests.models.Response],
+        fn: typing.Callable[..., requests.models.Response],
         endpoint: str,
         as_json: bool,
-        **kwargs: Unpack[SessionFunctionKwargs[TParams, TBody]],
+        **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]],
     ) -> TEntityDict | str:
         num_tries = 0
         last_exception: BaseException
@@ -188,20 +195,26 @@ def normalize_params(params: TParams) -> None:
             elif isinstance(params[key], bool) and not params[key]:
                 params[key] = 'false'
 
-    @overload
+    @typing.overload
     def get(
-        self, endpoint: str, as_json: Literal[False], params: TParams | None = None
-    ) -> str: ...
+        self,
+        endpoint: str,
+        as_json: typing.Literal[False],
+        params: TParams | None = None,
+    ) -> str:
 
-    @overload
+    @typing.overload
     def get(
-        self, endpoint: str, as_json: Literal[True], params: TParams | None = None
-    ) -> TEntityDict: ...
+        self,
+        endpoint: str,
+        as_json: typing.Literal[True],
+        params: TParams | None = None,
+    ) -> TEntityDict:
 
     def get(
         self,
         endpoint: str,
-        as_json: Literal[True] | Literal[False] = True,
+        as_json: typing.Literal[True] | typing.Literal[False] = True,
         params: TParams | None = None,
     ) -> TEntityDict | str:
         return self.make_request(
@@ -213,29 +226,29 @@ def get(
             verify=self.config.verify,
         )
 
-    @overload
+    @typing.overload
     def post(
         self,
         endpoint: str,
         body: TBody,
-        as_json: Literal[False],
+        as_json: typing.Literal[False],
         params: TParams | None = None,
-    ) -> str: ...
+    ) -> str:
 
-    @overload
+    @typing.overload
     def post(
         self,
         endpoint: str,
         body: TBody,
-        as_json: Literal[True],
+        as_json: typing.Literal[True],
         params: TParams | None = None,
-    ) -> TEntityDict: ...
+    ) -> TEntityDict:
 
     def post(
         self,
         endpoint: str,
         body: TBody,
-        as_json: Literal[True, False],
+        as_json: typing.Literal[True, False],
         params: TParams | None = None,
     ) -> str | TEntityDict:
         if params:

src/typesense/configuration.py

@@ -16,40 +16,46 @@
 
 from __future__ import annotations
 
+import sys
 import time
-from typing import Literal, NotRequired, TypedDict, Union
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
 from urllib.parse import urlparse
 
 from typesense.exceptions import ConfigError
 from typesense.logger import logger
 
 
-class NodeConfigDict(TypedDict):
+class NodeConfigDict(typing.TypedDict):
     """
     A dictionary that represents the configuration for a node in the Typesense cluster.
 
     Attributes:
         host (str): The host name of the node.
         port (int): The port number of the node.
         path (str, optional): The path of the node.
-        protocol (Literal['http', 'https'] | str): The protocol of the node.
+        protocol (typing.Literal['http', 'https'] | str): The protocol of the node.
     """
 
     host: str
     port: int
-    path: NotRequired[str]
-    protocol: Literal['http', 'https'] | str
+    path: typing.NotRequired[str]
+    protocol: typing.Literal["http", "https"] | str
 
 
-class ConfigDict(TypedDict):
+class ConfigDict(typing.TypedDict):
     """
     A dictionary that represents the configuration for the Typesense client.
 
     Attributes:
-        nodes (list[Union[str, NodeConfigDict]]): A list of dictionaries or URLs that
+        nodes (list[typing.Union[str, NodeConfigDict]]): A list of dictionaries or URLs that
             represent the nodes in the cluster.
 
-        nearest_node (Union[str, NodeConfigDict]): A dictionary or URL
+        nearest_node (typing.Union[str, NodeConfigDict]): A dictionary or URL
             that represents the nearest node to the client.
 
         api_key (str): The API key to use for authentication.
@@ -65,23 +71,25 @@ class ConfigDict(TypedDict):
 
         timeout_seconds (int, deprecated): The connection timeout in seconds.
 
-        master_node (Union[str, NodeConfigDict], deprecated): A dictionary or
+        master_node (typing.Union[str, NodeConfigDict], deprecated): A dictionary or
             URL that represents the master node.
 
-        read_replica_nodes (list[Union[str, NodeConfigDict]], deprecated): A list of
+        read_replica_nodes (list[typing.Union[str, NodeConfigDict]], deprecated): A list of
             dictionaries or URLs that represent the read replica nodes.
     """
 
-    nodes: list[Union[str, NodeConfigDict]]
-    nearest_node: NotRequired[Union[str, NodeConfigDict]]
+    nodes: list[typing.Union[str, NodeConfigDict]]
+    nearest_node: typing.NotRequired[typing.Union[str, NodeConfigDict]]
     api_key: str
-    num_retries: NotRequired[int]
-    interval_seconds: NotRequired[int]
-    healthcheck_interval_seconds: NotRequired[int]
-    verify: NotRequired[bool]
-    timeout_seconds: NotRequired[int]  # deprecated
-    master_node: NotRequired[Union[str, NodeConfigDict]]  # deprecated
-    read_replica_nodes: NotRequired[list[Union[str, NodeConfigDict]]]  # deprecated
+    num_retries: typing.NotRequired[int]
+    interval_seconds: typing.NotRequired[int]
+    healthcheck_interval_seconds: typing.NotRequired[int]
+    verify: typing.NotRequired[bool]
+    timeout_seconds: typing.NotRequired[int]  # deprecated
+    master_node: typing.NotRequired[typing.Union[str, NodeConfigDict]]  # deprecated
+    read_replica_nodes: typing.NotRequired[
+        list[typing.Union[str, NodeConfigDict]]
+    ]  # deprecated
 
 
 class Node:
@@ -92,7 +100,7 @@ class Node:
         host (str): The host name of the node.
         port (str | int): The port number of the node.
         path (str): The path of the node.
-        protocol (Literal['http', 'https'] | str): The protocol of the node.
+        protocol (typing.Literal['http', 'https'] | str): The protocol of the node.
         healthy (bool): Whether the node is healthy or not.
     """
 
@@ -101,7 +109,7 @@ def __init__(
         host: str,
         port: str | int,
         path: str,
-        protocol: Literal['http', 'https'] | str,
+        protocol: typing.Literal["http", "https"] | str,
     ) -> None:
         """
         Initialize a Node object with the specified host, port, path, and protocol.
@@ -110,7 +118,7 @@ def __init__(
             host (str): The host name of the node.
             port (str | int): The port number of the node.
             path (str): The path of the node.
-            protocol (Literal['http', 'https'] | str): The protocol of the node.
+            protocol (typing.Literal['http', 'https'] | str): The protocol of the node.
         """
         self.host = host
         self.port = port
@@ -208,8 +216,8 @@ def __init__(
 
     def _handle_nearest_node(
         self,
-        nearest_node: Union[str, NodeConfigDict, None],
-    ) -> Union[Node, None]:
+        nearest_node: typing.Union[str, NodeConfigDict, None],
+    ) -> typing.Union[Node, None]:
         """
         Handle the nearest node configuration.
 
@@ -225,7 +233,7 @@ def _handle_nearest_node(
 
     def _initialize_nodes(
         self,
-        node: Union[str, NodeConfigDict],
+        node: typing.Union[str, NodeConfigDict],
     ) -> Node:
         """
         Handle the initialization of a node.
@@ -286,7 +294,7 @@ def validate_required_config_fields(config_dict: ConfigDict) -> None:
             raise ConfigError('`api_key` is not defined.')
 
     @staticmethod
-    def validate_nodes(nodes: list[Union[str, NodeConfigDict]]) -> None:
+    def validate_nodes(nodes: list[typing.Union[str, NodeConfigDict]]) -> None:
         """
         Validate the nodes in the configuration dictionary.
 
@@ -309,7 +317,7 @@ def validate_nodes(nodes: list[Union[str, NodeConfigDict]]) -> None:
                 )
 
     @staticmethod
-    def validate_nearest_node(nearest_node: Union[str, NodeConfigDict]) -> None:
+    def validate_nearest_node(nearest_node: typing.Union[str, NodeConfigDict]) -> None:
         """
         Validate the nearest node in the configuration dictionary.