refactor: Enhance type safety for generic resource handling and improve documentation for API client context manager usage and resource extraction.

Author: sergioteula

amazon_creatorsapi/aio/api.py

@@ -7,7 +7,8 @@
 
 import asyncio
 import time
-from typing import TYPE_CHECKING, Any
+from enum import Enum
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from typing_extensions import Self
 
@@ -40,7 +41,6 @@
 from creatorsapi_python_sdk.models.search_items_resource import SearchItemsResource
 
 if TYPE_CHECKING:
-    from enum import Enum
     from types import TracebackType
 
     from amazon_creatorsapi.core.marketplaces import CountryCode
@@ -59,6 +59,9 @@
 ENDPOINT_GET_VARIATIONS = "/catalog/v1/getVariations"
 ENDPOINT_GET_BROWSE_NODES = "/catalog/v1/getBrowseNodes"
 
+# TypeVar for generic resource handling
+ResourceT = TypeVar("ResourceT", bound=Enum)
+
 
 class AsyncAmazonCreatorsApi:
     """Async version of Amazon Creators API wrapper.
@@ -89,6 +92,13 @@ class AsyncAmazonCreatorsApi:
     The context manager approach is more efficient when making multiple
     requests in quick succession due to HTTP connection pooling.
 
+    Note:
+        Using without context manager creates a new HTTP connection for each
+        request, which is less efficient and may impact performance. For
+        production code making multiple API calls, always use the context
+        manager (async with) to benefit from connection pooling and reduced
+        overhead.
+
     Args:
         credential_id: Your Creators API credential ID.
         credential_secret: Your Creators API credential secret.
@@ -524,8 +534,16 @@ def _handle_error_response(self, status_code: int, body: str) -> None:
         msg = f"Request failed with status {status_code}{body_info}"
         raise RequestError(msg)
 
-    def _get_all_resources(self, resource_class: type[Enum]) -> list[Any]:
-        """Extract all resource values from a resource enum class."""
+    def _get_all_resources(self, resource_class: type[ResourceT]) -> list[ResourceT]:
+        """Extract all resource values from a resource enum class.
+
+        Args:
+            resource_class: Enum class containing resource definitions.
+
+        Returns:
+            List of all enum members from the resource class.
+
+        """
         return list(resource_class)
 
     def _deserialize_items(self, items_data: list[dict[str, Any]]) -> list[Item]: