tessl/pypi-google-cloud-shell

Google Cloud Shell API client library for programmatic environment management.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Google Cloud Shell

Name: tessl/pypi-google-cloud-shell
Author: tessl

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