client.py

"""
This file is auto generated by the code generation script.
Do not modify this file manually.
Use the `make codegen` command to regenerate.

当前文件为自动生成的控制 API 客户端代码。请勿手动修改此文件。
使用 `make codegen` 命令重新生成。

source: agentrun/sandbox/__client_async_template.py

Sandbox客户端模板 / Sandbox Client Template

此模板用于生成沙箱客户端代码。
This template is used to generate sandbox client code.
"""

import time
from typing import Any, Dict, List, Optional, TYPE_CHECKING

from alibabacloud_agentrun20250910.models import (
    CreateTemplateInput,
    ListSandboxesRequest,
    ListTemplatesRequest,
    UpdateTemplateInput,
)

from agentrun.sandbox.api import SandboxControlAPI, SandboxDataAPI
from agentrun.sandbox.model import (
    ListSandboxesInput,
    ListSandboxesOutput,
    NASConfig,
    OSSMountConfig,
    PageableInput,
    PolarFsConfig,
    TemplateInput,
)
from agentrun.utils.config import Config
from agentrun.utils.exception import (
    AgentRunError,
    ClientError,
    ResourceNotExistError,
)

from .sandbox import Sandbox

if TYPE_CHECKING:
    from agentrun.sandbox.template import Template


class SandboxClient:
    """Sandbox 客户端 / Sandbox Client

    用于管理 Sandbox 和 Template。
    Used for managing Sandboxes and Templates.
    """

    def __init__(self, config: Optional[Config] = None):
        """初始化 Sandbox 客户端 / Initialize Sandbox client

        Args:
            config: 配置对象,可选 / Configuration object, optional
        """
        self.__control_api = SandboxControlAPI(config=config)
        self.__sandbox_data_api = SandboxDataAPI(config=config)

    async def _wait_template_ready_async(
        self,
        template_name: str,
        config: Optional[Config] = None,
        interval_seconds: int = 5,
        timeout_seconds: int = 300,
    ) -> "Template":
        """Wait for Template to be ready (async)

        Args:
            template_name: Template name
            config: Config object
            interval_seconds: Polling interval in seconds
            timeout_seconds: Timeout in seconds

        Returns:
            Template: Ready Template object

        Raises:
            TimeoutError: Timeout error
            ClientError: Client error
        """
        import asyncio

        start_time = time.time()
        while True:
            template = await self.get_template_async(
                template_name, config=config
            )

            # Check if ready
            if template.status == "READY":
                return template

            # Check if failed
            if (
                template.status == "CREATE_FAILED"
                or template.status == "UPDATE_FAILED"
            ):
                raise AgentRunError(
                    f"Template {template_name} creation failed, status:"
                    f" {template.status}"
                )

            # Check timeout
            if time.time() - start_time > timeout_seconds:
                raise TimeoutError(
                    f"Timeout waiting for Template {template_name} to be ready,"
                    f" current status: {template.status}"
                )

            await asyncio.sleep(interval_seconds)

    def _wait_template_ready(
        self,
        template_name: str,
        config: Optional[Config] = None,
        interval_seconds: int = 5,
        timeout_seconds: int = 300,
    ) -> "Template":
        """Wait for Template to be ready (async)

        Args:
            template_name: Template name
            config: Config object
            interval_seconds: Polling interval in seconds
            timeout_seconds: Timeout in seconds

        Returns:
            Template: Ready Template object

        Raises:
            TimeoutError: Timeout error
            ClientError: Client error
        """

        start_time = time.time()
        while True:
            template = self.get_template(template_name, config=config)

            # Check if ready
            if template.status == "READY":
                return template

            # Check if failed
            if (
                template.status == "CREATE_FAILED"
                or template.status == "UPDATE_FAILED"
            ):
                raise AgentRunError(
                    f"Template {template_name} creation failed, status:"
                    f" {template.status}"
                )

            # Check timeout
            if time.time() - start_time > timeout_seconds:
                raise TimeoutError(
                    f"Timeout waiting for Template {template_name} to be ready,"
                    f" current status: {template.status}"
                )

            time.sleep(interval_seconds)

    async def create_template_async(
        self, input: TemplateInput, config: Optional[Config] = None
    ) -> "Template":
        """创建 Template（异步）

        Args:
            input: Template 配置
            config: 配置对象

        Returns:
            Template: 创建的 Template 对象

        Raises:
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        from agentrun.sandbox.template import Template

        # 转换为 SDK 需要的格式
        sdk_input = CreateTemplateInput().from_map(
            input.model_dump(by_alias=True)
        )
        result = await self.__control_api.create_template_async(
            sdk_input, config=config
        )
        template = Template.from_inner_object(result)

        # Poll and wait for Template to be ready
        template = await self._wait_template_ready_async(
            template.template_name or "", config=config
        )

        return template

    def create_template(
        self, input: TemplateInput, config: Optional[Config] = None
    ) -> "Template":
        """创建 Template（同步）

        Args:
            input: Template 配置
            config: 配置对象

        Returns:
            Template: 创建的 Template 对象

        Raises:
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        from agentrun.sandbox.template import Template

        # 转换为 SDK 需要的格式
        sdk_input = CreateTemplateInput().from_map(
            input.model_dump(by_alias=True)
        )
        result = self.__control_api.create_template(sdk_input, config=config)
        template = Template.from_inner_object(result)

        # Poll and wait for Template to be ready
        template = self._wait_template_ready(
            template.template_name or "", config=config
        )

        return template

    async def delete_template_async(
        self, template_name: str, config: Optional[Config] = None
    ) -> "Template":
        """删除 Template（异步）

        Args:
            template_name: Template 名称
            config: 配置对象

        Returns:
            Template: 删除的 Template 对象

        Raises:
            ResourceNotExistError: Template 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        from agentrun.sandbox.template import Template

        try:
            result = await self.__control_api.delete_template_async(
                template_name, config=config
            )
            return Template.from_inner_object(result)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Template", template_name) from e
            raise e

    def delete_template(
        self, template_name: str, config: Optional[Config] = None
    ) -> "Template":
        """删除 Template（同步）

        Args:
            template_name: Template 名称
            config: 配置对象

        Returns:
            Template: 删除的 Template 对象

        Raises:
            ResourceNotExistError: Template 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        from agentrun.sandbox.template import Template

        try:
            result = self.__control_api.delete_template(
                template_name, config=config
            )
            return Template.from_inner_object(result)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Template", template_name) from e
            raise e

    async def update_template_async(
        self,
        template_name: str,
        input: TemplateInput,
        config: Optional[Config] = None,
    ) -> "Template":
        """更新 Template（异步）

        Args:
            template_name: Template 名称
            input: Template 更新配置
            config: 配置对象

        Returns:
            Template: 更新后的 Template 对象

        Raises:
            ResourceNotExistError: Template 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        from agentrun.sandbox.template import Template

        try:
            # 转换为 SDK 需要的格式
            sdk_input = UpdateTemplateInput().from_map(
                input.model_dump(by_alias=True, exclude_none=True)
            )
            result = await self.__control_api.update_template_async(
                template_name, sdk_input, config=config
            )
            return Template.from_inner_object(result)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Template", template_name) from e
            raise e

    def update_template(
        self,
        template_name: str,
        input: TemplateInput,
        config: Optional[Config] = None,
    ) -> "Template":
        """更新 Template（同步）

        Args:
            template_name: Template 名称
            input: Template 更新配置
            config: 配置对象

        Returns:
            Template: 更新后的 Template 对象

        Raises:
            ResourceNotExistError: Template 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        from agentrun.sandbox.template import Template

        try:
            # 转换为 SDK 需要的格式
            sdk_input = UpdateTemplateInput().from_map(
                input.model_dump(by_alias=True, exclude_none=True)
            )
            result = self.__control_api.update_template(
                template_name, sdk_input, config=config
            )
            return Template.from_inner_object(result)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Template", template_name) from e
            raise e

    async def get_template_async(
        self, template_name: str, config: Optional[Config] = None
    ) -> "Template":
        """获取 Template（异步）

        Args:
            template_name: Template 名称
            config: 配置对象

        Returns:
            Template: Template 对象

        Raises:
            ResourceNotExistError: Template 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        from agentrun.sandbox.template import Template

        try:
            result = await self.__control_api.get_template_async(
                template_name, config=config
            )
            return Template.from_inner_object(result)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Template", template_name) from e
            raise e

    def get_template(
        self, template_name: str, config: Optional[Config] = None
    ) -> "Template":
        """获取 Template（同步）

        Args:
            template_name: Template 名称
            config: 配置对象

        Returns:
            Template: Template 对象

        Raises:
            ResourceNotExistError: Template 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        from agentrun.sandbox.template import Template

        try:
            result = self.__control_api.get_template(
                template_name, config=config
            )
            return Template.from_inner_object(result)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Template", template_name) from e
            raise e

    async def list_templates_async(
        self,
        input: Optional[PageableInput] = None,
        config: Optional[Config] = None,
    ) -> List["Template"]:
        """枚举 Templates（异步）

        Args:
            input: 分页配置
            config: 配置对象

        Returns:
            List[Template]: Template 列表

        Raises:
            ClientError: 客户端错误
            ServerError: 服务器错误
            TimeoutError: Timeout waiting for Template to be ready
        """
        from agentrun.sandbox.template import Template

        if input is None:
            input = PageableInput()

        # 转换为 SDK 需要的格式
        sdk_input = ListTemplatesRequest().from_map(
            input.model_dump(by_alias=True)
        )
        results = await self.__control_api.list_templates_async(
            sdk_input, config=config
        )
        return (
            [Template.from_inner_object(item) for item in results.items]
            if results.items
            else []
        )

    def list_templates(
        self,
        input: Optional[PageableInput] = None,
        config: Optional[Config] = None,
    ) -> List["Template"]:
        """枚举 Templates（同步）

        Args:
            input: 分页配置
            config: 配置对象

        Returns:
            List[Template]: Template 列表

        Raises:
            ClientError: 客户端错误
            ServerError: 服务器错误
            TimeoutError: Timeout waiting for Template to be ready
        """
        from agentrun.sandbox.template import Template

        if input is None:
            input = PageableInput()

        # 转换为 SDK 需要的格式
        sdk_input = ListTemplatesRequest().from_map(
            input.model_dump(by_alias=True)
        )
        results = self.__control_api.list_templates(sdk_input, config=config)
        return (
            [Template.from_inner_object(item) for item in results.items]
            if results.items
            else []
        )

    async def create_sandbox_async(
        self,
        template_name: str,
        sandbox_idle_timeout_seconds: Optional[int] = 600,
        sandbox_id: Optional[str] = None,
        nas_config: Optional[NASConfig] = None,
        oss_mount_config: Optional[OSSMountConfig] = None,
        polar_fs_config: Optional[PolarFsConfig] = None,
        config: Optional[Config] = None,
    ) -> Sandbox:
        """创建 Sandbox（异步） / Create Sandbox (async)

        Args:
            template_name: 模板名称 / Template name
            sandbox_idle_timeout_seconds: 沙箱空闲超时时间（秒） / Sandbox idle timeout (seconds)
            sandbox_id: 沙箱 ID（可选，用户可指定） / Sandbox ID (optional, user can specify)
            nas_config: NAS 配置 / NAS configuration
            oss_mount_config: OSS 挂载配置 / OSS mount configuration
            polar_fs_config: PolarFS 配置 / PolarFS configuration
            config: 配置对象 / Config object

        Returns:
            Sandbox: 创建的 Sandbox 对象 / Created Sandbox object

        Raises:
            ClientError: 客户端错误 / Client error
            ServerError: 服务器错误 / Server error
        """
        # 将配置对象转换为字典格式
        nas_config_dict: Optional[Dict[str, Any]] = None
        if nas_config is not None:
            nas_config_dict = nas_config.model_dump(by_alias=True)

        oss_mount_config_dict: Optional[Dict[str, Any]] = None
        if oss_mount_config is not None:
            oss_mount_config_dict = oss_mount_config.model_dump(by_alias=True)

        polar_fs_config_dict: Optional[Dict[str, Any]] = None
        if polar_fs_config is not None:
            polar_fs_config_dict = polar_fs_config.model_dump(by_alias=True)

        result = await self.__sandbox_data_api.create_sandbox_async(
            template_name=template_name,
            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
            sandbox_id=sandbox_id,
            nas_config=nas_config_dict,
            oss_mount_config=oss_mount_config_dict,
            polar_fs_config=polar_fs_config_dict,
            config=config,
        )

        # 判断返回结果是否成功
        if result.get("code") != "SUCCESS":
            raise ClientError(
                status_code=0,
                message=(
                    "Failed to create sandbox:"
                    f" {result.get('message', 'Unknown error')}"
                ),
            )

        # 从 data 字段中提取数据并实例化（使用 model_validate 从字典创建）
        data = result.get("data", {})
        return Sandbox.model_validate(data, by_alias=True)

    def create_sandbox(
        self,
        template_name: str,
        sandbox_idle_timeout_seconds: Optional[int] = 600,
        sandbox_id: Optional[str] = None,
        nas_config: Optional[NASConfig] = None,
        oss_mount_config: Optional[OSSMountConfig] = None,
        polar_fs_config: Optional[PolarFsConfig] = None,
        config: Optional[Config] = None,
    ) -> Sandbox:
        """创建 Sandbox（同步） / Create Sandbox (async)

        Args:
            template_name: 模板名称 / Template name
            sandbox_idle_timeout_seconds: 沙箱空闲超时时间（秒） / Sandbox idle timeout (seconds)
            sandbox_id: 沙箱 ID（可选，用户可指定） / Sandbox ID (optional, user can specify)
            nas_config: NAS 配置 / NAS configuration
            oss_mount_config: OSS 挂载配置 / OSS mount configuration
            polar_fs_config: PolarFS 配置 / PolarFS configuration
            config: 配置对象 / Config object

        Returns:
            Sandbox: 创建的 Sandbox 对象 / Created Sandbox object

        Raises:
            ClientError: 客户端错误 / Client error
            ServerError: 服务器错误 / Server error
        """
        # 将配置对象转换为字典格式
        nas_config_dict: Optional[Dict[str, Any]] = None
        if nas_config is not None:
            nas_config_dict = nas_config.model_dump(by_alias=True)

        oss_mount_config_dict: Optional[Dict[str, Any]] = None
        if oss_mount_config is not None:
            oss_mount_config_dict = oss_mount_config.model_dump(by_alias=True)

        polar_fs_config_dict: Optional[Dict[str, Any]] = None
        if polar_fs_config is not None:
            polar_fs_config_dict = polar_fs_config.model_dump(by_alias=True)

        result = self.__sandbox_data_api.create_sandbox(
            template_name=template_name,
            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
            sandbox_id=sandbox_id,
            nas_config=nas_config_dict,
            oss_mount_config=oss_mount_config_dict,
            polar_fs_config=polar_fs_config_dict,
            config=config,
        )

        # 判断返回结果是否成功
        if result.get("code") != "SUCCESS":
            raise ClientError(
                status_code=0,
                message=(
                    "Failed to create sandbox:"
                    f" {result.get('message', 'Unknown error')}"
                ),
            )

        # 从 data 字段中提取数据并实例化（使用 model_validate 从字典创建）
        data = result.get("data", {})
        return Sandbox.model_validate(data, by_alias=True)

    async def stop_sandbox_async(
        self, sandbox_id: str, config: Optional[Config] = None
    ) -> Sandbox:
        """停止 Sandbox（异步）

        Args:
            sandbox_id: Sandbox ID
            config: 配置对象

        Returns:
            Sandbox: 停止后的 Sandbox 对象

        Raises:
            ResourceNotExistError: Sandbox 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        try:
            result = await self.__sandbox_data_api.stop_sandbox_async(
                sandbox_id, config=config
            )

            # 判断返回结果是否成功
            if result.get("code") != "SUCCESS":
                raise ClientError(
                    status_code=0,
                    message=(
                        "Failed to stop sandbox:"
                        f" {result.get('message', 'Unknown error')}"
                    ),
                )

            # 从 data 字段中提取数据并实例化（使用 model_validate 从字典创建）
            data = result.get("data", {})
            return Sandbox.model_validate(data, by_alias=True)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Sandbox", sandbox_id) from e
            raise e

    def stop_sandbox(
        self, sandbox_id: str, config: Optional[Config] = None
    ) -> Sandbox:
        """停止 Sandbox（同步）

        Args:
            sandbox_id: Sandbox ID
            config: 配置对象

        Returns:
            Sandbox: 停止后的 Sandbox 对象

        Raises:
            ResourceNotExistError: Sandbox 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        try:
            result = self.__sandbox_data_api.stop_sandbox(
                sandbox_id, config=config
            )

            # 判断返回结果是否成功
            if result.get("code") != "SUCCESS":
                raise ClientError(
                    status_code=0,
                    message=(
                        "Failed to stop sandbox:"
                        f" {result.get('message', 'Unknown error')}"
                    ),
                )

            # 从 data 字段中提取数据并实例化（使用 model_validate 从字典创建）
            data = result.get("data", {})
            return Sandbox.model_validate(data, by_alias=True)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Sandbox", sandbox_id) from e
            raise e

    async def delete_sandbox_async(
        self, sandbox_id: str, config: Optional[Config] = None
    ) -> Sandbox:
        """删除 Sandbox（异步）

        Args:
            sandbox_id: Sandbox ID
            config: 配置对象

        Returns:
            Sandbox: 停止后的 Sandbox 对象

        Raises:
            ResourceNotExistError: Sandbox 不存在（包括 HTTP 404 与数据面业务层
                not-found 两种情形）。调用方可 catch 此异常实现幂等删除。
                Sandbox does not exist (covers both HTTP 404 and data-plane
                business-level not-found).  Callers can catch this exception
                for idempotent delete logic.
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        try:
            result = await self.__sandbox_data_api.delete_sandbox_async(
                sandbox_id, config=config
            )

            # 判断返回结果是否成功
            if result.get("code") != "SUCCESS":
                message = result.get("message", "")
                # 数据面报告 sandbox 不存在时，与 HTTP 404 路径保持一致，
                # 统一抛出 ResourceNotExistError，方便调用方幂等处理。
                # When the data plane reports sandbox not found, raise
                # ResourceNotExistError for consistency with the HTTP 404 path.
                # Callers can catch ResourceNotExistError to implement idempotent
                # deletion (e.g. when TERMINATED instances still appear in list
                # results but have already been removed from the data plane).
                # Note: long-term the server should return a stable error_code
                # (e.g. SandboxNotFound) so the SDK can match on that instead
                # of a message string.
                if "sandbox not found" in message.lower():
                    raise ResourceNotExistError("Sandbox", sandbox_id)
                raise ClientError(
                    status_code=0,
                    message=(
                        f"Failed to stop sandbox: {message or 'Unknown error'}"
                    ),
                )

            # 从 data 字段中提取数据并实例化（使用 model_validate 从字典创建）
            data = result.get("data", {})
            return Sandbox.model_validate(data, by_alias=True)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Sandbox", sandbox_id) from e
            raise e

    def delete_sandbox(
        self, sandbox_id: str, config: Optional[Config] = None
    ) -> Sandbox:
        """删除 Sandbox（同步）

        Args:
            sandbox_id: Sandbox ID
            config: 配置对象

        Returns:
            Sandbox: 停止后的 Sandbox 对象

        Raises:
            ResourceNotExistError: Sandbox 不存在（包括 HTTP 404 与数据面业务层
                not-found 两种情形）。调用方可 catch 此异常实现幂等删除。
                Sandbox does not exist (covers both HTTP 404 and data-plane
                business-level not-found).  Callers can catch this exception
                for idempotent delete logic.
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        try:
            result = self.__sandbox_data_api.delete_sandbox(
                sandbox_id, config=config
            )

            # 判断返回结果是否成功
            if result.get("code") != "SUCCESS":
                message = result.get("message", "")
                # 数据面报告 sandbox 不存在时，与 HTTP 404 路径保持一致，
                # 统一抛出 ResourceNotExistError，方便调用方幂等处理。
                # When the data plane reports sandbox not found, raise
                # ResourceNotExistError for consistency with the HTTP 404 path.
                # Callers can catch ResourceNotExistError to implement idempotent
                # deletion (e.g. when TERMINATED instances still appear in list
                # results but have already been removed from the data plane).
                # Note: long-term the server should return a stable error_code
                # (e.g. SandboxNotFound) so the SDK can match on that instead
                # of a message string.
                if "sandbox not found" in message.lower():
                    raise ResourceNotExistError("Sandbox", sandbox_id)
                raise ClientError(
                    status_code=0,
                    message=(
                        f"Failed to stop sandbox: {message or 'Unknown error'}"
                    ),
                )

            # 从 data 字段中提取数据并实例化（使用 model_validate 从字典创建）
            data = result.get("data", {})
            return Sandbox.model_validate(data, by_alias=True)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Sandbox", sandbox_id) from e
            raise e

    async def get_sandbox_async(
        self,
        sandbox_id: str,
        config: Optional[Config] = None,
    ) -> Sandbox:
        """获取 Sandbox（异步）

        Args:
            sandbox_id: Sandbox ID
            config: 配置对象

        Returns:
            Sandbox: Sandbox 对象

        Raises:
            ResourceNotExistError: Sandbox 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        try:
            result = await self.__sandbox_data_api.get_sandbox_async(
                sandbox_id, config=config
            )

            # 判断返回结果是否成功
            if result.get("code") != "SUCCESS":
                raise ClientError(
                    status_code=0,
                    message=(
                        "Failed to get sandbox:"
                        f" {result.get('message', 'Unknown error')}"
                    ),
                )

            # 从 data 字段中提取数据并实例化（使用 model_validate 从字典创建）
            data = result.get("data", {})
            return Sandbox.model_validate(data, by_alias=True)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Sandbox", sandbox_id) from e
            raise e

    def get_sandbox(
        self,
        sandbox_id: str,
        config: Optional[Config] = None,
    ) -> Sandbox:
        """获取 Sandbox（同步）

        Args:
            sandbox_id: Sandbox ID
            config: 配置对象

        Returns:
            Sandbox: Sandbox 对象

        Raises:
            ResourceNotExistError: Sandbox 不存在
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        try:
            result = self.__sandbox_data_api.get_sandbox(
                sandbox_id, config=config
            )

            # 判断返回结果是否成功
            if result.get("code") != "SUCCESS":
                raise ClientError(
                    status_code=0,
                    message=(
                        "Failed to get sandbox:"
                        f" {result.get('message', 'Unknown error')}"
                    ),
                )

            # 从 data 字段中提取数据并实例化（使用 model_validate 从字典创建）
            data = result.get("data", {})
            return Sandbox.model_validate(data, by_alias=True)
        except ClientError as e:
            if e.status_code == 404:
                raise ResourceNotExistError("Sandbox", sandbox_id) from e
            raise e

    async def list_sandboxes_async(
        self,
        input: Optional[ListSandboxesInput] = None,
        config: Optional[Config] = None,
    ) -> ListSandboxesOutput:
        """枚举 Sandboxes（异步）

        Args:
            input: 分页配置
            config: 配置对象

        Returns:
            List[Sandbox]: Sandbox 列表

        Raises:
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        if input is None:
            input = ListSandboxesInput()

        # 转换为 SDK 需要的格式
        sdk_input = ListSandboxesRequest().from_map(
            input.model_dump(by_alias=True)
        )

        results = await self.__control_api.list_sandboxes_async(
            sdk_input, config=config
        )
        return ListSandboxesOutput(
            sandboxes=[
                Sandbox.from_inner_object(item) for item in results.items
            ],
            next_token=results.next_token,
        )

    def list_sandboxes(
        self,
        input: Optional[ListSandboxesInput] = None,
        config: Optional[Config] = None,
    ) -> ListSandboxesOutput:
        """枚举 Sandboxes（同步）

        Args:
            input: 分页配置
            config: 配置对象

        Returns:
            List[Sandbox]: Sandbox 列表

        Raises:
            ClientError: 客户端错误
            ServerError: 服务器错误
        """
        if input is None:
            input = ListSandboxesInput()

        # 转换为 SDK 需要的格式
        sdk_input = ListSandboxesRequest().from_map(
            input.model_dump(by_alias=True)
        )

        results = self.__control_api.list_sandboxes(sdk_input, config=config)
        return ListSandboxesOutput(
            sandboxes=[
                Sandbox.from_inner_object(item) for item in results.items
            ],
            next_token=results.next_token,
        )