feat: Stream profile downloads as tar archives

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 127
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-6568ec20bad9bc5257619dae6b6817eedc308f8b74453912e660df95e329e44a.yml
-openapi_spec_hash: 17b9ed1a0a3193731c52c4b1aac2b5b8
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-5163e8941e42f7fb84e10f572f538202b31722c84bb980db74ccd44a960eb87f.yml
+openapi_spec_hash: 8aa974cf7843681d6ae3e6dcf099596d
 config_hash: 77ee715aa17061166f9a02b264a21b8d

api.md

@@ -288,7 +288,7 @@ Methods:
 - <code title="patch /profiles/{id_or_name}">client.profiles.<a href="./src/kernel/resources/profiles.py">update</a>(id_or_name, \*\*<a href="src/kernel/types/profile_update_params.py">params</a>) -> <a href="./src/kernel/types/profile.py">Profile</a></code>
 - <code title="get /profiles">client.profiles.<a href="./src/kernel/resources/profiles.py">list</a>(\*\*<a href="src/kernel/types/profile_list_params.py">params</a>) -> <a href="./src/kernel/types/profile.py">SyncOffsetPagination[Profile]</a></code>
 - <code title="delete /profiles/{id_or_name}">client.profiles.<a href="./src/kernel/resources/profiles.py">delete</a>(id_or_name) -> None</code>
-- <code title="get /profiles/{id_or_name}/download">client.profiles.<a href="./src/kernel/resources/profiles.py">download</a>(id_or_name) -> BinaryAPIResponse</code>
+- <code title="get /profiles/{id_or_name}/download">client.profiles.<a href="./src/kernel/resources/profiles.py">download</a>(id_or_name, \*\*<a href="src/kernel/types/profile_download_params.py">params</a>) -> BinaryAPIResponse</code>
 
 # Auth
 

src/kernel/resources/profiles.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+from typing_extensions import Literal
+
 import httpx
 
-from ..types import profile_list_params, profile_create_params, profile_update_params
+from ..types import profile_list_params, profile_create_params, profile_update_params, profile_download_params
 from .._types import Body, Omit, Query, Headers, NoneType, NotGiven, omit, not_given
 from .._utils import path_template, maybe_transform, async_maybe_transform
 from .._compat import cached_property
@@ -264,17 +266,25 @@ def download(
         self,
         id_or_name: str,
         *,
+        format: Literal["tar.zst", "tar"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> BinaryAPIResponse:
-        """
-        Returns a zstd-compressed tar file of the full user-data directory.
+        """Downloads the profile in its stored format by default.
+
+        Current profiles are
+        returned as zstd-compressed tar archives, while legacy profiles remain JSON. Set
+        `format=tar` to decompress current profiles during download; legacy profiles
+        remain JSON.
 
         Args:
+          format: Response format for current profile archives. Legacy profiles are always
+              returned as JSON.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -285,11 +295,15 @@ def download(
         """
         if not id_or_name:
             raise ValueError(f"Expected a non-empty value for `id_or_name` but received {id_or_name!r}")
-        extra_headers = {"Accept": "application/octet-stream", **(extra_headers or {})}
+        extra_headers = {"Accept": "application/zstd", **(extra_headers or {})}
         return self._get(
             path_template("/profiles/{id_or_name}/download", id_or_name=id_or_name),
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform({"format": format}, profile_download_params.ProfileDownloadParams),
             ),
             cast_to=BinaryAPIResponse,
         )
@@ -529,17 +543,25 @@ async def download(
         self,
         id_or_name: str,
         *,
+        format: Literal["tar.zst", "tar"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AsyncBinaryAPIResponse:
-        """
-        Returns a zstd-compressed tar file of the full user-data directory.
+        """Downloads the profile in its stored format by default.
+
+        Current profiles are
+        returned as zstd-compressed tar archives, while legacy profiles remain JSON. Set
+        `format=tar` to decompress current profiles during download; legacy profiles
+        remain JSON.
 
         Args:
+          format: Response format for current profile archives. Legacy profiles are always
+              returned as JSON.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -550,11 +572,15 @@ async def download(
         """
         if not id_or_name:
             raise ValueError(f"Expected a non-empty value for `id_or_name` but received {id_or_name!r}")
-        extra_headers = {"Accept": "application/octet-stream", **(extra_headers or {})}
+        extra_headers = {"Accept": "application/zstd", **(extra_headers or {})}
         return await self._get(
             path_template("/profiles/{id_or_name}/download", id_or_name=id_or_name),
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=await async_maybe_transform({"format": format}, profile_download_params.ProfileDownloadParams),
             ),
             cast_to=AsyncBinaryAPIResponse,
         )

src/kernel/types/__init__.py

@@ -67,6 +67,7 @@
 from .browser_update_response import BrowserUpdateResponse as BrowserUpdateResponse
 from .extension_list_response import ExtensionListResponse as ExtensionListResponse
 from .extension_upload_params import ExtensionUploadParams as ExtensionUploadParams
+from .profile_download_params import ProfileDownloadParams as ProfileDownloadParams
 from .proxy_retrieve_response import ProxyRetrieveResponse as ProxyRetrieveResponse
 from .browser_pool_list_params import BrowserPoolListParams as BrowserPoolListParams
 from .credential_create_params import CredentialCreateParams as CredentialCreateParams

src/kernel/types/profile_download_params.py

@@ -0,0 +1,15 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, TypedDict
+
+__all__ = ["ProfileDownloadParams"]
+
+
+class ProfileDownloadParams(TypedDict, total=False):
+    format: Literal["tar.zst", "tar"]
+    """Response format for current profile archives.
+
+    Legacy profiles are always returned as JSON.
+    """

tests/api_resources/test_profiles.py

@@ -11,7 +11,9 @@
 
 from kernel import Kernel, AsyncKernel
 from tests.utils import assert_matches_type
-from kernel.types import Profile
+from kernel.types import (
+    Profile,
+)
 from kernel._response import (
     BinaryAPIResponse,
     AsyncBinaryAPIResponse,
@@ -236,7 +238,20 @@ def test_path_params_delete(self, client: Kernel) -> None:
     def test_method_download(self, client: Kernel, respx_mock: MockRouter) -> None:
         respx_mock.get("/profiles/id_or_name/download").mock(return_value=httpx.Response(200, json={"foo": "bar"}))
         profile = client.profiles.download(
-            "id_or_name",
+            id_or_name="id_or_name",
+        )
+        assert profile.is_closed
+        assert profile.json() == {"foo": "bar"}
+        assert cast(Any, profile.is_closed) is True
+        assert isinstance(profile, BinaryAPIResponse)
+
+    @parametrize
+    @pytest.mark.respx(base_url=base_url)
+    def test_method_download_with_all_params(self, client: Kernel, respx_mock: MockRouter) -> None:
+        respx_mock.get("/profiles/id_or_name/download").mock(return_value=httpx.Response(200, json={"foo": "bar"}))
+        profile = client.profiles.download(
+            id_or_name="id_or_name",
+            format="tar.zst",
         )
         assert profile.is_closed
         assert profile.json() == {"foo": "bar"}
@@ -249,7 +264,7 @@ def test_raw_response_download(self, client: Kernel, respx_mock: MockRouter) ->
         respx_mock.get("/profiles/id_or_name/download").mock(return_value=httpx.Response(200, json={"foo": "bar"}))
 
         profile = client.profiles.with_raw_response.download(
-            "id_or_name",
+            id_or_name="id_or_name",
         )
 
         assert profile.is_closed is True
@@ -262,7 +277,7 @@ def test_raw_response_download(self, client: Kernel, respx_mock: MockRouter) ->
     def test_streaming_response_download(self, client: Kernel, respx_mock: MockRouter) -> None:
         respx_mock.get("/profiles/id_or_name/download").mock(return_value=httpx.Response(200, json={"foo": "bar"}))
         with client.profiles.with_streaming_response.download(
-            "id_or_name",
+            id_or_name="id_or_name",
         ) as profile:
             assert not profile.is_closed
             assert profile.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -278,7 +293,7 @@ def test_streaming_response_download(self, client: Kernel, respx_mock: MockRoute
     def test_path_params_download(self, client: Kernel) -> None:
         with pytest.raises(ValueError, match=r"Expected a non-empty value for `id_or_name` but received ''"):
             client.profiles.with_raw_response.download(
-                "",
+                id_or_name="",
             )
 
 
@@ -497,7 +512,20 @@ async def test_path_params_delete(self, async_client: AsyncKernel) -> None:
     async def test_method_download(self, async_client: AsyncKernel, respx_mock: MockRouter) -> None:
         respx_mock.get("/profiles/id_or_name/download").mock(return_value=httpx.Response(200, json={"foo": "bar"}))
         profile = await async_client.profiles.download(
-            "id_or_name",
+            id_or_name="id_or_name",
+        )
+        assert profile.is_closed
+        assert await profile.json() == {"foo": "bar"}
+        assert cast(Any, profile.is_closed) is True
+        assert isinstance(profile, AsyncBinaryAPIResponse)
+
+    @parametrize
+    @pytest.mark.respx(base_url=base_url)
+    async def test_method_download_with_all_params(self, async_client: AsyncKernel, respx_mock: MockRouter) -> None:
+        respx_mock.get("/profiles/id_or_name/download").mock(return_value=httpx.Response(200, json={"foo": "bar"}))
+        profile = await async_client.profiles.download(
+            id_or_name="id_or_name",
+            format="tar.zst",
         )
         assert profile.is_closed
         assert await profile.json() == {"foo": "bar"}
@@ -510,7 +538,7 @@ async def test_raw_response_download(self, async_client: AsyncKernel, respx_mock
         respx_mock.get("/profiles/id_or_name/download").mock(return_value=httpx.Response(200, json={"foo": "bar"}))
 
         profile = await async_client.profiles.with_raw_response.download(
-            "id_or_name",
+            id_or_name="id_or_name",
         )
 
         assert profile.is_closed is True
@@ -523,7 +551,7 @@ async def test_raw_response_download(self, async_client: AsyncKernel, respx_mock
     async def test_streaming_response_download(self, async_client: AsyncKernel, respx_mock: MockRouter) -> None:
         respx_mock.get("/profiles/id_or_name/download").mock(return_value=httpx.Response(200, json={"foo": "bar"}))
         async with async_client.profiles.with_streaming_response.download(
-            "id_or_name",
+            id_or_name="id_or_name",
         ) as profile:
             assert not profile.is_closed
             assert profile.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -539,5 +567,5 @@ async def test_streaming_response_download(self, async_client: AsyncKernel, resp
     async def test_path_params_download(self, async_client: AsyncKernel) -> None:
         with pytest.raises(ValueError, match=r"Expected a non-empty value for `id_or_name` but received ''"):
             await async_client.profiles.with_raw_response.download(
-                "",
+                id_or_name="",
             )