gbox_sdk.wrapper package

Subpackages

Submodules

gbox_sdk.wrapper.sdk module

class gbox_sdk.wrapper.sdk.BoxList

Bases: TypedDict

Parameters for listing boxes.

class gbox_sdk.wrapper.sdk.BoxListOperatorResponse(operators, page=None, page_size=None, total=None)

Bases: object

class gbox_sdk.wrapper.sdk.BoxTerminate

Bases: TypedDict

Parameters for terminating a box.

class gbox_sdk.wrapper.sdk.CreateAndroid

Bases: _CreateAndroidRequired, _CreateAndroidOptional

Parameters for creating an Android box with type specification.

config: Config
type: Literal['android']
wait: bool
class gbox_sdk.wrapper.sdk.CreateLinux

Bases: _CreateLinuxRequired, _CreateLinuxOptional

Parameters for creating a Linux box with type specification.

config: Config
type: Literal['linux']
wait: bool

gbox_sdk.wrapper.utils module

gbox_sdk.wrapper.utils.is_android_box(box)
Return type:

bool

gbox_sdk.wrapper.utils.is_linux_box(box)
Return type:

bool

Module contents

class gbox_sdk.wrapper.ActionOperator(client, box_id)

Bases: object

Provides high-level action operations for a specific box using the GboxClient.

Methods correspond to various box actions such as click, drag, swipe, type, screenshot, etc.

ai(body)

Perform an AI-powered action on the box.

Return type:

Union[AIActionScreenshotResult, AIActionResult]

Args:

body: Either a string instruction or ActionAI parameters.

Returns:

ActionAIResponse: The response from the AI action.

click(body)

Perform a click action on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionClickParams): Parameters for the click action.

Returns:

ActionClickResponse: The response from the click action.

drag(body)

Perform a drag action on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionDragParams): Parameters for the drag action.

Returns:

ActionDragResponse: The response from the drag action.

move(body)

Move an element or pointer on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionMoveParams): Parameters for the move action.

Returns:

ActionMoveResponse: The response from the move action.

press_button(body)

Simulate a button press on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionPressButtonParams): Parameters for the button press action.

Returns:

ActionPressButtonResponse: The response from the button press action.

press_key(body)

Simulate a key press on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionPressKeyParams): Parameters for the key press action.

Returns:

ActionPressKeyResponse: The response from the key press action.

screen_rotation(body)

Rotate the screen of the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionScreenRotationParams): Parameters for the screen rotation action.

Returns:

ActionScreenRotationResponse: The response from the screen rotation action.

screenshot(body=None)

Take a screenshot of the box.

Return type:

ActionScreenshotResponse

Args:
body (Optional[ActionScreenshot]): Parameters for the screenshot action.

If not provided, defaults to base64 output format.

Returns:

ActionScreenshotResponse: The response containing the screenshot data.

Examples:

Take a screenshot and return base64 data: >>> response = action_operator.screenshot()

Take a screenshot and save to file: >>> response = action_operator.screenshot({“path”: “/path/to/screenshot.png”})

Take a screenshot with specific format: >>> response = action_operator.screenshot({“output_format”: “base64”})

scroll(body)

Perform a scroll action on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionScrollParams): Parameters for the scroll action.

Returns:

ActionScrollResponse: The response from the scroll action.

swipe(body)

Perform a swipe action on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionSwipeParams): Parameters for the swipe action.

Returns:

ActionSwipeResponse: The response from the swipe action.

touch(body)

Simulate a touch action on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionTouchParams): Parameters for the touch action.

Returns:

ActionTouchResponse: The response from the touch action.

type(body)

Simulate typing text on the box.

Return type:

Union[ActionIncludeScreenshotResult, ActionCommonResult]

Args:

body (ActionTypeParams): Parameters for the type action.

Returns:

ActionTypeResponse: The response from the type action.

class gbox_sdk.wrapper.ActionScreenshot

Bases: ActionScreenshotParams

Extends ActionScreenshotParams to optionally include a file path for saving the screenshot.

Attributes:

path (Optional[str]): The file path where the screenshot will be saved.

clip: Clip
output_format: Annotated[Literal['base64', 'storageKey']]
path: Optional[str]
class gbox_sdk.wrapper.AndroidAppOperator(client, box, data)

Bases: object

Operator class for managing a specific Android app within a box.

Provides methods to open, restart, close, list activities, and backup the app.

Attributes:

client (GboxClient): The API client used for communication. box (AndroidBox): The Android box data object. data (AndroidApp): The app data object.

backup()

Backup the app.

Return type:

BinaryAPIResponse

Returns:

BinaryAPIResponse: The backup response containing binary data.

close()

Close the app.

Return type:

None

list_activities()

List all activities of the app.

Return type:

AndroidListActivitiesResponse

Returns:

AndroidListActivitiesResponse: The response containing the list of activities.

open(activity_name=None)

Open the app, optionally specifying an activity name.

Return type:

None

Args:

activity_name (str, optional): The activity name to open. Defaults to None.

restart(activity_name=None)

Restart the app, optionally specifying an activity name.

Return type:

None

Args:

activity_name (str, optional): The activity name to restart. Defaults to None.

class gbox_sdk.wrapper.AndroidBoxOperator(client, data)

Bases: BaseBox

Operator class for managing Android boxes, providing access to app and package management functionalities.

Attributes:

app (AndroidAppManager): Manager for Android app operations. pkg (AndroidPkgManager): Manager for Android package operations.

class gbox_sdk.wrapper.AndroidPkgOperator(client, box, data)

Bases: object

Operator class for managing a specific Android package within a box.

Provides methods to open, close, restart, list activities, and backup the package.

Attributes:

client (GboxClient): The API client used for communication. box (AndroidBox): The Android box data object. data (AndroidGetResponse): The package data object.

backup()

Backup the package.

Return type:

BinaryAPIResponse

Returns:

BinaryAPIResponse: The backup response containing binary data.

close()

Close the package.

Return type:

None

list_activities()

List all activities of the package.

Return type:

AndroidListActivitiesResponse

Returns:

AndroidListActivitiesResponse: The response containing the list of activities.

open(activity_name=None)

Open the package, optionally specifying an activity name.

Return type:

None

Args:

activity_name (str, optional): The activity name to open. Defaults to None.

restart(activity_name=None)

Restart the package, optionally specifying an activity name.

Return type:

None

Args:

activity_name (str, optional): The activity name to restart. Defaults to None.

class gbox_sdk.wrapper.BaseBox(client, data)

Bases: object

Base class for box operations, providing common interfaces for box lifecycle and actions.

Attributes:

client (GboxClient): The Gbox client instance used for API calls. data (Union[LinuxBox, AndroidBox]): The box data object. action (ActionOperator): Operator for box actions. fs (FileSystemOperator): Operator for file system actions. browser (BrowserOperator): Operator for browser actions.

command(body)

Execute shell commands in the box.

Return type:

BoxExecuteCommandsResponse

Args:

body (Union[BoxExecuteCommandsParams, str, List[str]]): The commands to execute or parameters object.

Returns:

BoxExecuteCommandsResponse: The response containing the command execution result.

live_view(body=None)

Get the live view URL for the box.

Return type:

BoxLiveViewURLResponse

Args:

body (BoxLiveViewURLParams): Parameters for live view URL.

Returns:

BoxLiveViewURLResponse: The response containing the live view URL.

run_code(body)

Run code in the box.

Return type:

BoxRunCodeResponse

Args:

body (Union[BoxRunCodeParams, str]): The code to run or parameters object.

Returns:

BoxRunCodeResponse: The response containing the code execution result.

start(body=None)

Start the box.

Return type:

Self

Args:

body (Optional[BoxStartParams]): Parameters for starting the box.

Returns:

Self: The updated box instance for method chaining.

stop(body=None)

Stop the box.

Return type:

Self

Args:

body (Optional[BoxStopParams]): Parameters for stopping the box.

Returns:

Self: The updated box instance for method chaining.

terminate(body=None)

Terminate the box.

Return type:

Self

Args:

body (Optional[BoxTerminateParams]): Parameters for terminating the box.

Returns:

Self: The updated box instance for method chaining.

web_terminal(body=None)

Get the web terminal URL for the box.

Return type:

BoxWebTerminalURLResponse

Args:

body (BoxWebTerminalURLParams): Parameters for web terminal URL.

Returns:

BoxWebTerminalURLResponse: The response containing the web terminal URL.

class gbox_sdk.wrapper.BrowserOperator(client, box_id)

Bases: object

Provides operations related to browser management for a specific box.

Args:

client (GboxClient): The GboxClient instance used to interact with the API. box_id (str): The unique identifier of the box.

cdp_url()

Get the Chrome DevTools Protocol (CDP) URL for the browser in the specified box.

Return type:

str

Returns:

str: The CDP URL for the browser.

class gbox_sdk.wrapper.DirectoryOperator(client, box_id, data)

Bases: object

Operator for directory operations within a box.

Provides methods to list and rename a directory.

Args:

client (GboxClient): The Gbox client instance. box_id (str): The ID of the box to operate on. data (DataDir): The directory data.

list(body=None)

List files and directories in this directory, returning operator objects.

Return type:

List[Union[FileOperator, DirectoryOperator]]

Args:

body (Optional[FListParams]): Parameters for listing. If None, uses the directory’s path.

Returns:

List[Union[FileOperator, DirectoryOperator]]: List of file or directory operator objects.

list_info(body=None)

Get detailed information about files and directories in this directory.

Return type:

FListResponse

Args:

body (Optional[FListParams]): Parameters for listing. If None, uses the directory’s path.

Returns:

FListResponse: The response containing file/directory information.

rename(body)

Rename this directory.

Return type:

Union[File, Dir]

Args:

body (FRenameParams): Parameters for renaming the directory.

Returns:

FRenameResponse: The response after renaming.

class gbox_sdk.wrapper.FileOperator(client, box_id, data)

Bases: object

Operator for file operations within a box.

Provides methods to read, write, and rename a file.

Args:

client (GboxClient): The Gbox client instance. box_id (str): The ID of the box to operate on. data (DataFile): The file data.

read(body=None)

Read the content of this file.

Return type:

FReadResponse

Args:

body (Optional[FReadParams]): Parameters for reading the file. If None, uses the file’s path.

Returns:

FReadResponse: The response containing file content.

rename(body)

Rename this file.

Return type:

Union[File, Dir]

Args:

body (FRenameParams): Parameters for renaming the file.

Returns:

FRenameResponse: The response after renaming.

write(body)

Write content to this file (text or binary).

Return type:

FWriteResponse

Args:
body (Union[WriteFile, WriteFileByBinary]): Parameters for writing to the file.

Can be either WriteFile (for text content) or WriteFileByBinary (for binary content).

Returns:

FWriteResponse: The response after writing.

class gbox_sdk.wrapper.FileSystemOperator(client, box_id)

Bases: object

Operator for file system operations within a box.

Provides methods to list, read, write, remove, check existence, rename, and retrieve file or directory information in a box.

Args:

client (GboxClient): The Gbox client instance. box_id (str): The ID of the box to operate on.

data_to_operator(data)

Convert a Data object to the corresponding operator.

Return type:

Union[FileOperator, DirectoryOperator]

Args:

data (Optional[Data]): The data object to convert.

Returns:

Union[FileOperator, DirectoryOperator]: The corresponding operator object.

Raises:

ValueError: If data is None.

exists(body)

Check if a file or directory exists.

Return type:

Union[ExistsFileResult, NotExistsFileResult]

Args:

body (FExistsParams): Parameters for checking existence.

Returns:

FExistsResponse: The response indicating existence.

get(body)

Get an operator for a file or directory by its information.

Return type:

Union[FileOperator, DirectoryOperator]

Args:

body (FInfoParams): Parameters for retrieving file or directory info.

Returns:

Union[FileOperator, DirectoryOperator]: The corresponding operator object.

list(body)

List files and directories at a given path or with given parameters, returning operator objects.

Return type:

List[Union[FileOperator, DirectoryOperator]]

Args:

body (Union[FListParams, str]): Path as a string or FListParams object.

Returns:

List[Union[FileOperator, DirectoryOperator]]: List of file or directory operator objects.

list_info(body)

Get detailed information about files and directories at a given path or with given parameters.

Return type:

FListResponse

Args:

body (Union[FListParams, str]): Path as a string or FListParams object.

Returns:

FListResponse: The response containing file/directory information.

read(body)

Read the content of a file.

Return type:

FReadResponse

Args:

body (FReadParams): Parameters for reading the file.

Returns:

FReadResponse: The response containing file content.

remove(body)

Remove a file or directory.

Return type:

FRemoveResponse

Args:

body (FRemoveParams): Parameters for removing the file or directory.

Returns:

None

rename(body)

Rename a file or directory.

Return type:

Union[File, Dir]

Args:

body (FRenameParams): Parameters for renaming.

Returns:

FRenameResponse: The response after renaming.

write(body)

Write content to a file (text or binary).

Return type:

FileOperator

Args:
body (Union[WriteFile, WriteFileByBinary]): Parameters for writing to the file.

Can be either WriteFile (for text content) or WriteFileByBinary (for binary content).

Returns:

FileOperator: The file operator for the written file.

class gbox_sdk.wrapper.GboxSDK(*, api_key=None, base_url=None, timeout=NOT_GIVEN, max_retries=None, default_headers=None, default_query=None, http_client=None, _strict_response_validation=None)

Bases: object

GboxSDK provides a high-level interface for managing and operating Gbox containers (boxes).

This SDK allows users to create, list, retrieve, and terminate both Android and Linux boxes, and provides operator objects for further box-specific operations. It wraps the lower-level GboxClient and exposes convenient methods for common workflows.

Attributes:

client (GboxClient): The underlying client used for API communication.

Examples:

Initialize the SDK: ```python from gbox_sdk.wrapper import GboxSDK

# Initialize the SDK sdk = GboxSDK(api_key=”your-api-key”) ```

Create boxes using the unified create method: ```python # Create an Android box android_box = sdk.create({“type”: “android”, “config”: {“labels”: {“env”: “test”}}})

# Create a Linux box linux_box = sdk.create({“type”: “linux”, “config”: {“envs”: {“PYTHON_VERSION”: “3.9”}}}) ```

List and manage boxes: ```python # List all boxes boxes = sdk.list()

# Get a specific box box = sdk.get(“box_id”)

# Terminate a box sdk.terminate(“box_id”) ```

create(body)

Create a new box and return its operator.

This method provides a unified interface for creating both Android and Linux boxes. The box type is determined by the ‘type’ field in the body parameter.

Return type:

Union[AndroidBoxOperator, LinuxBoxOperator]

Args:
body (CreateParams): Parameters for creating the box. Must include a ‘type’ field

specifying either ‘android’ or ‘linux’.

Returns:

BoxOperator: Operator for the created box (AndroidBoxOperator or LinuxBoxOperator).

Raises:

ValueError: If an unsupported box type is provided.

Examples:

Create an Android box: `python android_box = sdk.create({"type": "android", "config": {"labels": {"env": "test"}}}) `

Create a Linux box: `python linux_box = sdk.create({"type": "linux", "config": {"envs": {"PYTHON_VERSION": "3.9"}}}) `

data_to_operator(data)

Convert box data to the corresponding operator object.

Return type:

Union[AndroidBoxOperator, LinuxBoxOperator]

Args:

data (Union[AndroidBox, LinuxBox]): The box data to convert.

Returns:

BoxOperator: The corresponding operator object.

Raises:

ValueError: If the box type is invalid.

get(box_id)

Retrieve a specific box and return its operator object.

Return type:

Union[AndroidBoxOperator, LinuxBoxOperator]

Args:

box_id (str): The ID of the box to retrieve.

Returns:

BoxOperator: Operator object for the specified box.

Example:

`python box = sdk.get("975fed9f-bb28-4718-a2c5-e01f72864bd1") `

get_client()

Get the underlying GboxClient instance.

Return type:

GboxClient

Returns:

GboxClient: The underlying client instance.

get_info(box_id)

Retrieve detailed information for a specific box.

Return type:

Union[LinuxBox, AndroidBox]

Args:

box_id (str): The ID of the box to retrieve.

Returns:

BoxRetrieveResponse: Detailed information about the box.

Example:

`python box_info = sdk.get_info("975fed9f-bb28-4718-a2c5-e01f72864bd1") `

list(query=None)

List all boxes matching the query and return their operator objects.

Return type:

BoxListOperatorResponse

Args:

query (Optional[BoxList]): Query parameters for listing boxes.

Returns:

BoxListOperatorResponse: Response containing operator objects and pagination info.

Examples:

```python # List all boxes boxes = sdk.list()

# List with pagination boxes = sdk.list({“page”: 1, “page_size”: 10}) ```

list_info(query=None)

List information of all boxes matching the query.

Return type:

BoxListResponse

Args:

query (Optional[BoxList]): Query parameters for listing boxes.

Returns:

BoxListResponse: Response containing box information.

Examples:

```python # List all boxes boxes = sdk.list_info()

# List with pagination boxes = sdk.list_info({“page”: 1, “page_size”: 10}) ```

terminate(box_id, body=None)

Terminate a specific box.

Return type:

None

Args:

box_id (str): The ID of the box to terminate. body (Optional[BoxTerminate]): Additional parameters for termination.

Example:

`python sdk.terminate("box_id") `

class gbox_sdk.wrapper.LinuxBoxOperator(client, data)

Bases: BaseBox

Operator class for managing Linux boxes via the Gbox SDK. Provides an interface to interact with and control Linux-based boxes.