or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

clients.mdenvironments.mdindex.mdssh-keys.md
tile.json

tessl/pypi-google-cloud-shell

Google Cloud Shell API client library for programmatic environment management.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/google-cloud-shell@1.12.x

To install, run

npx @tessl/cli install tessl/pypi-google-cloud-shell@1.12.0

index.mddocs/

Google Cloud Shell

Google Cloud Shell API client library for programmatic management of Cloud Shell environments. Each user has at least one environment (ID "default") consisting of a Docker image and persistent home directory that remains across sessions. This library enables starting environments, managing SSH keys, and handling OAuth authorization.

Package Information

  • Package Name: google-cloud-shell
  • Package Type: pypi
  • Language: Python
  • Installation: pip install google-cloud-shell

Core Imports

from google.cloud.shell import CloudShellServiceClient, CloudShellServiceAsyncClient

Import specific types:

from google.cloud.shell import (
    Environment,
    GetEnvironmentRequest,
    StartEnvironmentRequest,
    AddPublicKeyRequest,
    CloudShellErrorDetails
)

Basic Usage

from google.cloud.shell import CloudShellServiceClient

# Initialize client
client = CloudShellServiceClient()

# Get environment information
environment = client.get_environment(
    name="users/me/environments/default"
)
print(f"Environment state: {environment.state}")
print(f"SSH connection: {environment.ssh_username}@{environment.ssh_host}:{environment.ssh_port}")

# Start environment (long-running operation)
operation = client.start_environment(
    name="users/me/environments/default"
)
response = operation.result()  # Wait for completion
print(f"Started environment: {response.environment.name}")

Architecture

The Google Cloud Shell API follows Google Cloud client library patterns:

  • Client Classes: Synchronous (CloudShellServiceClient) and asynchronous (CloudShellServiceAsyncClient) clients
  • Long-Running Operations: Most mutating operations return operation.Operation objects that can be polled for completion
  • Resource Paths: Structured resource names following the pattern users/{owner}/environments/{environment_id}
  • Authentication: Uses Google Auth library with service account or user credentials
  • Transport Options: Support for gRPC and REST transports

Capabilities

Client Management

Client initialization, configuration, and lifecycle management for both synchronous and asynchronous operations.

class CloudShellServiceClient:
    def __init__(
        self,
        *,
        credentials: Optional[ga_credentials.Credentials] = None,
        transport: Optional[Union[str, CloudShellServiceTransport, Callable]] = None,
        client_options: Optional[Union[ClientOptions, dict]] = None,
        client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
    ) -> None: ...

class CloudShellServiceAsyncClient:
    def __init__(
        self,
        *,
        credentials: Optional[ga_credentials.Credentials] = None,
        transport: Optional[Union[str, CloudShellServiceTransport, Callable]] = "grpc_asyncio",
        client_options: Optional[ClientOptions] = None,
        client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
    ) -> None: ...

Client Management

Environment Operations

Core operations for managing Cloud Shell environments including getting environment details, starting environments, and handling OAuth authorization.

def get_environment(
    self,
    request: Optional[Union[cloudshell.GetEnvironmentRequest, dict]] = None,
    *,
    name: Optional[str] = None,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
) -> cloudshell.Environment: ...

def start_environment(
    self,
    request: Optional[Union[cloudshell.StartEnvironmentRequest, dict]] = None,
    *,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
) -> operation.Operation: ...

def authorize_environment(
    self,
    request: Optional[Union[cloudshell.AuthorizeEnvironmentRequest, dict]] = None,
    *,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
) -> operation.Operation: ...

Environment Operations

SSH Key Management

Operations for managing SSH public keys associated with Cloud Shell environments, enabling secure SSH connections.

def add_public_key(
    self,
    request: Optional[Union[cloudshell.AddPublicKeyRequest, dict]] = None,
    *,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
) -> operation.Operation: ...

def remove_public_key(
    self,
    request: Optional[Union[cloudshell.RemovePublicKeyRequest, dict]] = None,
    *,
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
) -> operation.Operation: ...

SSH Key Management

Types

Core Environment Type

class Environment(proto.Message):
    """A Cloud Shell environment combining Docker image and persistent home directory."""
    
    name: str                           # Immutable resource name: users/{owner}/environments/{id}
    id: str                            # Output only environment identifier
    docker_image: str                  # Required immutable Docker image path
    state: Environment.State           # Output only current execution state
    web_host: str                      # Output only HTTPS/WSS connection host
    ssh_username: str                  # Output only SSH username
    ssh_host: str                      # Output only SSH connection host
    ssh_port: int                      # Output only SSH connection port
    public_keys: MutableSequence[str]  # Output only associated public keys

class State(proto.Enum):
    STATE_UNSPECIFIED = 0  # Unknown state
    SUSPENDED = 1          # Not running, can be started
    PENDING = 2           # Starting but not ready
    RUNNING = 3           # Running and ready for connections
    DELETING = 4          # Being deleted

Error Handling

class CloudShellErrorDetails(proto.Message):
    """Cloud Shell-specific error information."""
    
    code: CloudShellErrorDetails.CloudShellErrorCode

class CloudShellErrorCode(proto.Enum):
    CLOUD_SHELL_ERROR_CODE_UNSPECIFIED = 0  # Unknown error
    IMAGE_UNAVAILABLE = 1                   # Docker image unavailable
    CLOUD_SHELL_DISABLED = 2               # Cloud Shell disabled by admin
    TOS_VIOLATION = 4                      # Terms of Service violation
    QUOTA_EXCEEDED = 5                     # Weekly quota exhausted
    ENVIRONMENT_UNAVAILABLE = 6            # Environment unavailable