Merge branch 'feat/add_file_sdk' into 'integration_2025-11-13_1083916009218'

feat: [development task] ark runtime (1828603)

See merge request iaasng/volcengine-python-sdk!918

Author: BitsAdmin

volcenginesdkarkruntime/__init__.py

@@ -1,4 +1,3 @@
-
 # Copyright (c) [2025] [OpenAI]
 # Copyright (c) [2025] [ByteDance Ltd. and/or its affiliates.]
 # SPDX-License-Identifier: Apache-2.0

volcenginesdkarkruntime/_base_client.py

@@ -1,4 +1,3 @@
-
 # Copyright (c) [2025] [OpenAI]
 # Copyright (c) [2025] [ByteDance Ltd. and/or its affiliates.]
 # SPDX-License-Identifier: Apache-2.0
@@ -19,19 +18,20 @@
 from random import random
 from types import TracebackType
 from typing import (
-    Type,
-    Dict,
-    TypeVar,
-    Any,
-    Optional,
-    cast,
     TYPE_CHECKING,
+    Any,
+    Dict,
+    Type,
     Union,
     Generic,
+    Mapping,
+    TypeVar,
     Iterable,
-    AsyncIterator,
     Iterator,
-    Generator
+    Optional,
+    Generator,
+    AsyncIterator,
+    cast,
 )
 from typing_extensions import override
 
@@ -44,6 +44,7 @@
 from httpx._types import RequestFiles
 
 from . import _exceptions  # type: ignore
+from ._qs import Querystring
 from ._constants import (
     DEFAULT_MAX_RETRIES,
     DEFAULT_TIMEOUT,
@@ -60,6 +61,7 @@
     ArkAPIStatusError,
     ArkAPIResponseValidationError,
 )
+from ._files import to_httpx_files, async_to_httpx_files
 from ._models import construct_type, GenericModel
 from ._request_options import RequestOptions, ExtraRequestOptions
 from ._response import ArkAPIResponse, ArkAsyncAPIResponse
@@ -71,14 +73,17 @@
     PostParser,
     Body,
     Query,
+    HttpxRequestFiles,
 )
-from ._utils._utils import _gen_request_id, is_given, is_mapping
-from ._compat import model_copy, PYDANTIC_V2
+from ._utils._utils import _gen_request_id, is_given, is_mapping, is_dict, is_list
+from ._compat import model_copy, PYDANTIC_V2, model_dump
 
 SyncPageT = TypeVar("SyncPageT", bound="BaseSyncPage[Any]")
 AsyncPageT = TypeVar("AsyncPageT", bound="BaseAsyncPage[Any]")
 
 _T = TypeVar("_T")
+_T_co = TypeVar("_T_co", covariant=True)
+
 _StreamT = TypeVar("_StreamT", bound=Stream[Any])
 _AsyncStreamT = TypeVar("_AsyncStreamT", bound=AsyncStream[Any])
 
@@ -177,6 +182,10 @@ def __init__(
                 "max_retries cannot be None. If you want to disable retries, pass `0`; if you want unlimited retries, pass `math.inf` or a very high number`"
             )
 
+    @property
+    def qs(self) -> Querystring:
+        return Querystring()
+
     @property
     def auth_headers(self) -> dict[str, str]:
         return {}
@@ -219,9 +228,13 @@ def _should_stream_response_body(self, request: httpx.Request) -> bool:
     def _build_request(
         self,
         options: RequestOptions,
+        *,
+        retries_taken: int = 0,
     ) -> httpx.Request:
         if log.isEnabledFor(logging.DEBUG):
-            log.debug("Request options: %s", options.model_dump(exclude_unset=True))
+            log.debug("Request options: %s", model_dump(options, exclude_unset=True))
+
+        kwargs: dict[str, Any] = {}
 
         body = options.body
         if options.extra_body is not None:
@@ -236,16 +249,105 @@ def _build_request(
 
         headers = self._build_headers(options)
         params = options.params
+        content_type = headers.get("Content-Type")
+        files = options.files
+
+        # If the given Content-Type header is multipart/form-data then it
+        # has to be removed so that httpx can generate the header with
+        # additional information for us as it has to be in this form
+        # for the server to be able to correctly parse the request:
+        # multipart/form-data; boundary=---abc--
+        if content_type is not None and content_type.startswith("multipart/form-data"):
+            if "boundary" not in content_type:
+                # only remove the header if the boundary hasn't been explicitly set
+                # as the caller doesn't want httpx to come up with their own boundary
+                headers.pop("Content-Type")
+
+            # As we are now sending multipart/form-data instead of application/json
+            # we need to tell httpx to use it, https://www.python-httpx.org/advanced/clients/#multipart-file-encoding
+            if body:
+                if not is_dict(body):
+                    raise TypeError(
+                        f"Expected query input to be a dictionary for multipart requests but got {type(body)} instead."
+                    )
+                kwargs["data"] = self._serialize_multipartform(body)
+
+            # httpx determines whether or not to send a "multipart/form-data"
+            # request based on the truthiness of the "files" argument.
+            # This gets around that issue by generating a dict value that
+            # evaluates to true.
+            #
+            # https://github.com/encode/httpx/discussions/2399#discussioncomment-3814186
+            if not files:
+                files = cast(HttpxRequestFiles, ForceMultipartDict())
+
+        prepared_url = self._prepare_url(options.url)
+        if "_" in prepared_url.host:
+            # work around https://github.com/encode/httpx/discussions/2880
+            kwargs["extensions"] = {"sni_hostname": prepared_url.host.replace("_", "-")}
+
+        is_body_allowed = options.method.lower() != "get"
+
+        if is_body_allowed:
+            if isinstance(body, bytes):
+                kwargs["content"] = body
+            else:
+                kwargs["json"] = body if is_given(body) else None
+            kwargs["files"] = files
+        else:
+            headers.pop("Content-Type", None)
+            kwargs.pop("data", None)
 
+        # TODO: report this error to httpx
         return self._client.build_request(  # pyright: ignore[reportUnknownMemberType]
             headers=headers,
-            timeout=options.timeout if options.timeout else self.timeout,
+            timeout=self.timeout
+            if isinstance(options.timeout, NotGiven)
+            else options.timeout,
             method=options.method,
-            url=self._prepare_url(options.url),
-            params=params,  # type: ignore
-            json=body,
+            url=prepared_url,
+            # the `Query` type that we use is incompatible with qs'
+            # `Params` type as it needs to be typed as `Mapping[str, object]`
+            # so that passing a `TypedDict` doesn't cause an error.
+            # https://github.com/microsoft/pyright/issues/3526#event-6715453066
+            params=self.qs.stringify(cast(Mapping[str, Any], params))
+            if params
+            else None,
+            **kwargs,
         )
 
+    def _serialize_multipartform(
+        self, data: Mapping[object, object]
+    ) -> dict[str, object]:
+        items = self.qs.stringify_items(
+            # TODO: type ignore is required as stringify_items is well typed but we can't be
+            # well typed without heavy validation.
+            data,  # type: ignore
+            array_format="brackets",
+        )
+        serialized: dict[str, object] = {}
+        for key, value in items:
+            existing = serialized.get(key)
+
+            if not existing:
+                serialized[key] = value
+                continue
+
+            # If a value has already been set for this key then that
+            # means we're sending data like `array[]=[1, 2, 3]` and we
+            # need to tell httpx that we want to send multiple values with
+            # the same key which is done by using a list or a tuple.
+            #
+            # Note: 2d arrays should never result in the same key at both
+            # levels so it's safe to assume that if the value is a list,
+            # it was because we changed it to be a list.
+            if is_list(existing):
+                existing.append(value)
+            else:
+                serialized[key] = [existing, value]
+
+        return serialized
+
     def _calculate_retry_timeout(
         self,
         remaining_retries: int,
@@ -595,7 +697,7 @@ def post(
         opts = RequestOptions.construct(  # type: ignore
             method="post",
             url=path,
-            files=files,
+            files=to_httpx_files(files),
             body=body,
             **options,
         )
@@ -678,7 +780,9 @@ def get_api_list(
         options: ExtraRequestOptions = {},
         method: str = "get",
     ) -> AsyncPageT:
-        opts = RequestOptions.construct(method=method, url=path, json_data=body, **options)
+        opts = RequestOptions.construct(
+            method=method, url=path, json_data=body, **options
+        )
         return self._request_api_list(model, page, opts)
 
     def _request_api_list(
@@ -815,7 +919,7 @@ async def post(
             method="post",
             url=path,
             body=body,
-            files=files,
+            files=await async_to_httpx_files(files),
             **options,
         )
 
@@ -890,7 +994,9 @@ async def get_api_list(
         options: ExtraRequestOptions = {},
         method: str = "get",
     ) -> AsyncPageT:
-        opts = RequestOptions.construct(method=method, url=path, json_data=body, **options)
+        opts = RequestOptions.construct(
+            method=method, url=path, json_data=body, **options
+        )
         return await self._request_api_list(model, page, opts)
 
     async def _request_api_list(
@@ -1229,7 +1335,9 @@ def get_next_page(self: SyncPageT) -> SyncPageT:
             )
 
         options = self._info_to_options(info)
-        return self._client._request_api_list(self._model, page=self.__class__, options=options)
+        return self._client._request_api_list(
+            self._model, page=self.__class__, options=options
+        )
 
 
 class AsyncPaginator(Generic[_T, AsyncPageT]):
@@ -1309,4 +1417,23 @@ async def get_next_page(self: AsyncPageT) -> AsyncPageT:
             )
 
         options = self._info_to_options(info)
-        return await self._client._request_api_list(self._model, page=self.__class__, options=options)
+        return await self._client._request_api_list(
+            self._model, page=self.__class__, options=options
+        )
+
+
+class ForceMultipartDict(Dict[str, None]):
+    def __bool__(self) -> bool:
+        return True
+
+
+def _merge_mappings(
+    obj1: Mapping[_T_co, Union[_T, None]],
+    obj2: Mapping[_T_co, Union[_T, None]],
+) -> Dict[_T_co, _T]:
+    """Merge two mappings of the same type, removing any values that are instances of `Omit`.
+
+    In cases with duplicate keys the second mapping takes precedence.
+    """
+    merged = {**obj1, **obj2}
+    return {key: value for key, value in merged.items() if value is not None}

volcenginesdkarkruntime/_client.py

@@ -1,4 +1,3 @@
-
 # Copyright (c) [2025] [OpenAI]
 # Copyright (c) [2025] [ByteDance Ltd. and/or its affiliates.]
 # SPDX-License-Identifier: Apache-2.0
@@ -65,6 +64,7 @@ class Ark(SyncAPIClient):
     batch: batch.Batch
     model_breaker_map: dict[str, ModelBreaker]
     model_breaker_lock: threading.Lock
+    files: resources.Files
 
     def __init__(
         self,
@@ -134,6 +134,7 @@ def __init__(
         self.batch = batch.Batch(self)
         self.model_breaker_map = defaultdict(ModelBreaker)
         self.model_breaker_lock = threading.Lock()
+        self.files = resources.Files(self)
         # self.classification = resources.Classification(self)
 
     def _get_endpoint_sts_token(self, endpoint_id: str):
@@ -143,7 +144,9 @@ def _get_endpoint_sts_token(self, endpoint_id: str):
             self._sts_token_manager = StsTokenManager(self.ak, self.sk, self.region)
         return self._sts_token_manager.get(endpoint_id)
 
-    def _get_endpoint_certificate(self, endpoint_id: str) -> Tuple[key_agreement_client, str, str, float]:
+    def _get_endpoint_certificate(
+        self, endpoint_id: str
+    ) -> Tuple[key_agreement_client, str, str, float]:
         if self._certificate_manager is None:
             cert_path = os.environ.get("E2E_CERTIFICATE_PATH")
             if (
@@ -194,6 +197,7 @@ class AsyncArk(AsyncAPIClient):
     batch: batch.AsyncBatch
     model_breaker_map: dict[str, ModelBreaker]
     model_breaker_lock: asyncio.Lock
+    files: resources.AsyncFiles
 
     def __init__(
         self,
@@ -263,6 +267,7 @@ def __init__(
         self.batch = batch.AsyncBatch(self)
         self.model_breaker_map = defaultdict(ModelBreaker)
         self.model_breaker_lock = asyncio.Lock()
+        self.files = resources.AsyncFiles(self)
         # self.classification = resources.AsyncClassification(self)
 
     def _get_endpoint_sts_token(self, endpoint_id: str):
@@ -279,7 +284,9 @@ def _get_bot_sts_token(self, bot_id: str):
             self._sts_token_manager = StsTokenManager(self.ak, self.sk, self.region)
         return self._sts_token_manager.get(bot_id, resource_type="bot")
 
-    def _get_endpoint_certificate(self, endpoint_id: str) -> Tuple[key_agreement_client, str, str, float]:
+    def _get_endpoint_certificate(
+        self, endpoint_id: str
+    ) -> Tuple[key_agreement_client, str, str, float]:
         if self._certificate_manager is None:
             cert_path = os.environ.get("E2E_CERTIFICATE_PATH")
             if (
@@ -429,7 +436,9 @@ def __init__(
         base_url: str | URL = BASE_URL,
         api_key: str | None = None,
     ):
-        self._certificate_manager: Dict[str, Tuple[key_agreement_client, str, str, float]] = {}
+        self._certificate_manager: Dict[
+            str, Tuple[key_agreement_client, str, str, float]
+        ] = {}
 
         # local cache prepare
         self._init_local_cert_cache()
@@ -542,7 +551,8 @@ def _init_local_cert_cache(self):
                 pass
             except Exception as e:
                 raise ArkAPIError(
-                    "failed to create certificate directory %s: %s\n" % (self._cert_storage_path, e)
+                    "failed to create certificate directory %s: %s\n"
+                    % (self._cert_storage_path, e)
                 )
 
     def get(self, ep: str) -> Tuple[key_agreement_client, str, str, float]:
@@ -558,9 +568,7 @@ def get(self, ep: str) -> Tuple[key_agreement_client, str, str, float]:
                 self._save_cert_to_file(ep, cert_pem)
             ring, key, exp_time = get_cert_info(cert_pem)
             self._certificate_manager[ep] = (
-                key_agreement_client(
-                    certificate_pem_string=cert_pem
-                ),
+                key_agreement_client(certificate_pem_string=cert_pem),
                 ring,
                 key,
                 exp_time,

volcenginesdkarkruntime/_compat.py

@@ -1,4 +1,3 @@
-
 # Copyright (c) [2025] [OpenAI]
 # Copyright (c) [2025] [ByteDance Ltd. and/or its affiliates.]
 # SPDX-License-Identifier: Apache-2.0

volcenginesdkarkruntime/_constants.py

@@ -1,4 +1,3 @@
-
 # Copyright (c) [2025] [OpenAI]
 # Copyright (c) [2025] [ByteDance Ltd. and/or its affiliates.]
 # SPDX-License-Identifier: Apache-2.0

volcenginesdkarkruntime/_exceptions.py

@@ -1,4 +1,3 @@
-
 # Copyright (c) [2025] [OpenAI]
 # Copyright (c) [2025] [ByteDance Ltd. and/or its affiliates.]
 # SPDX-License-Identifier: Apache-2.0

volcenginesdkarkruntime/_files.py

@@ -1,4 +1,3 @@
-
 # Copyright (c) [2025] [OpenAI]
 # Copyright (c) [2025] [ByteDance Ltd. and/or its affiliates.]
 # SPDX-License-Identifier: Apache-2.0