feat: make API parameters explicit for better IDE support

Author: kevin

dashscope/api_entities/aio_session.py

@@ -16,6 +16,9 @@
 import aiohttp
 import certifi
 
+from dashscope.common.constants import (
+    DEFAULT_CONNECTION_POOL_IDLE_TIMEOUT_SECONDS,
+)
 from dashscope.common.logging import logger
 
 _shared_ssl_context: Optional[ssl.SSLContext] = None
@@ -38,7 +41,8 @@ async def get_shared_aio_session() -> aiohttp.ClientSession:
 
     The session is lazily created on first use and reused for all
     subsequent calls on the same event loop. Connection pooling (keep-alive)
-    is handled by the underlying TCPConnector.
+    is handled by the underlying TCPConnector with idle timeout configured
+    to close stale connections.
     """
     loop = asyncio.get_running_loop()
 
@@ -47,7 +51,10 @@ async def get_shared_aio_session() -> aiohttp.ClientSession:
         if session is not None and not session.closed:
             return session
 
-        connector = aiohttp.TCPConnector(ssl=get_ssl_context())
+        connector = aiohttp.TCPConnector(
+            ssl=get_ssl_context(),
+            keepalive_timeout=DEFAULT_CONNECTION_POOL_IDLE_TIMEOUT_SECONDS,
+        )
         session = aiohttp.ClientSession(connector=connector, trust_env=True)
 
         _aio_sessions[loop] = session

dashscope/api_entities/api_request_factory.py

@@ -1,9 +1,14 @@
 # -*- coding: utf-8 -*-
 # Copyright (c) Alibaba, Inc. and its affiliates.
+from typing import Any, Dict, Union
 from urllib.parse import urlencode
 
+import aiohttp
+import requests
+
 import dashscope
 from dashscope.api_entities.api_request_data import ApiRequestData
+from dashscope.api_entities.encryption import Encryption
 from dashscope.api_entities.http_request import HttpRequest
 from dashscope.api_entities.websocket_request import WebSocketRequest
 from dashscope.common.constants import (
@@ -15,7 +20,6 @@
 from dashscope.common.error import InputDataRequired, UnsupportedApiProtocol
 from dashscope.common.logging import logger
 from dashscope.protocol.websocket import WebsocketStreamingMode
-from dashscope.api_entities.encryption import Encryption
 
 
 def _get_protocol_params(kwargs):
@@ -70,35 +74,111 @@ def _get_protocol_params(kwargs):
 
 
 def _build_api_request(  # pylint: disable=too-many-branches
+    # pylint: disable=too-many-arguments,too-many-locals
     model: str,
     input: object,  # pylint: disable=redefined-builtin
     task_group: str,
     task: str,
     function: str,
     api_key: str,
-    is_service=True,
+    is_service: bool = True,
+    # Protocol and connection configuration
+    api_protocol: ApiProtocol = ApiProtocol.HTTPS,
+    http_method: HTTPMethod = HTTPMethod.POST,
+    stream: bool = False,
+    async_request: bool = False,
+    request_timeout: int = None,
+    # WebSocket specific
+    ws_stream_mode: WebsocketStreamingMode = WebsocketStreamingMode.OUT,
+    is_binary_input: bool = False,
+    # HTTP specific
+    query: bool = False,
+    headers: Dict[str, str] = None,
+    form: Dict = None,
+    resources: Dict = None,
+    base_address: str = None,
+    flattened_output: bool = False,
+    extra_url_parameters: Dict[str, Any] = None,
+    user_agent: str = "",
+    session: Union[requests.Session, aiohttp.ClientSession] = None,
+    task_id: str = None,
+    enable_encryption: bool = False,
+    pre_task_id: str = None,
+    # Additional parameters for API request data
     **kwargs,
 ):
-    (
-        api_protocol,
-        ws_stream_mode,
-        is_binary_input,
-        http_method,
-        stream,
-        async_request,
-        query,
-        headers,
-        request_timeout,
-        form,
-        resources,
-        base_address,
-        flattened_output,
-        extra_url_parameters,
-        user_agent,
-        session,
-    ) = _get_protocol_params(kwargs)
-    task_id = kwargs.pop("task_id", None)
-    enable_encryption = kwargs.pop("enable_encryption", False)
+    # pylint: disable=too-many-statements
+    """Build API request object.
+
+    Args:
+        model (str): The model name.
+        input (object): The input data for the request.
+        task_group (str): The task group for the API path.
+        task (str): The task name for the API path.
+        function (str): The function name for the API path.
+        api_key (str): The API key for authentication.
+        is_service (bool, optional): Whether this is a service call.
+            Defaults to True.
+        api_protocol (ApiProtocol, optional): The protocol to use
+            (HTTP, HTTPS, WEBSOCKET). Defaults to ApiProtocol.HTTPS.
+        http_method (HTTPMethod, optional): The HTTP method (GET, POST).
+            Defaults to HTTPMethod.POST.
+        stream (bool, optional): Enable streaming output.
+            Defaults to False.
+        async_request (bool, optional): Enable async request.
+            Defaults to False.
+        request_timeout (int, optional): Request timeout in seconds.
+            Defaults to None.
+        ws_stream_mode (WebsocketStreamingMode, optional): WebSocket
+            streaming mode. Defaults to WebsocketStreamingMode.OUT.
+        is_binary_input (bool, optional): Whether input is binary data.
+            Defaults to False.
+        query (bool, optional): Whether this is a query request.
+            Defaults to False.
+        headers (Dict[str, str], optional): Additional HTTP headers.
+            Defaults to None.
+        form (Dict, optional): Form data for multipart requests.
+            Defaults to None.
+        resources (Dict, optional): Resource data. Defaults to None.
+        base_address (str, optional): Custom base URL for the API.
+            Defaults to None.
+        flattened_output (bool, optional): Whether to flatten output.
+            Defaults to False.
+        extra_url_parameters (Dict[str, Any], optional): Extra URL query
+            parameters. Defaults to None.
+        user_agent (str, optional): Custom user agent string.
+            Defaults to "".
+        session (Union[requests.Session, aiohttp.ClientSession], optional):
+            Custom session for connection reuse. Defaults to None.
+        task_id (str, optional): Task ID for the request.
+            Defaults to None.
+        enable_encryption (bool, optional): Enable request encryption.
+            Defaults to False.
+        pre_task_id (str, optional): Previous task ID for WebSocket.
+            Defaults to None.
+        **kwargs: Additional parameters passed to the API request data.
+
+    Returns:
+        HttpRequest or WebSocketRequest: The constructed request object.
+
+    Raises:
+        InputDataRequired: If input data is missing or invalid.
+        UnsupportedApiProtocol: If the API protocol is not supported.
+    """
+    # Handle stream mode for WebSocket
+    if not stream and ws_stream_mode == WebsocketStreamingMode.OUT:
+        ws_stream_mode = WebsocketStreamingMode.NONE
+
+    # Handle user_agent from headers
+    if headers and "user-agent" in headers:
+        header_ua = headers.pop("user-agent")
+        if user_agent:
+            user_agent = (
+                f"{header_ua}; {user_agent}" if header_ua else user_agent
+            )
+        else:
+            user_agent = header_ua
+
     encryption = None
 
     if api_protocol in [ApiProtocol.HTTP, ApiProtocol.HTTPS]:
@@ -146,7 +226,6 @@ def _build_api_request(  # pylint: disable=too-many-branches
             websocket_url = base_address
         else:
             websocket_url = dashscope.base_websocket_api_url
-        pre_task_id = kwargs.pop("pre_task_id", None)
         request = WebSocketRequest(
             url=websocket_url,
             api_key=api_key,