# Python SDK

> Every method and option of the Sandscale Python SDK (sandscale 0.2.0), generated from its source.

sandscale 0.2.0. Every method and option, generated from the SDK source.

[SDK overview](https://sandscale.dev/docs/sdks) · [Errors](https://sandscale.dev/docs/api/errors) · [Regions](https://sandscale.dev/docs/concepts/regions)

## Client

**Coming soon: the Python SDK is not on PyPI yet. This reference shows how it will work.**

```sh
pip install sandscale

from sandscale import Sandscale
sandscale = Sandscale()  # reads SANDSCALE_API_KEY
```

Create one client and reuse it. Its methods are grouped by area below. Every call also takes a `region`.

## `sandscale.sandboxes`

### `create`

```
sandscale.sandboxes.create(*, template: Optional[str]=None, snapshot_id: Optional[str]=None, cpu_count: Optional[int]=None, memory_mb: Optional[int]=None, disk_mb: Optional[int]=None, timeout_seconds: Optional[int]=None, env: Optional[Mapping[str, str]]=None, vault_env: Optional[Sequence[Union[VaultEnvRef, Mapping[str, str]]]]=None, command: Optional[Sequence[str]]=None, name: Optional[str]=None, labels: Optional[Mapping[str, str]]=None, metadata: Optional[Mapping[str, str]]=None, region: Optional[str]=None) -> Sandbox
```

Starts a sandbox. Limits, entitlement and policy are decided by the server.

### `get`

```
sandscale.sandboxes.get(sandbox_id: str, *, region: Optional[str]=None) -> Sandbox
```

### `list`

```
sandscale.sandboxes.list(*, status: Optional[str]=None, project_id: Optional[str]=None, limit: Optional[int]=None, cursor: Optional[str]=None, region: Optional[str]=None) -> ListResult[Sandbox]
```

Lists sandboxes: of one region when one is named, else of every live region.

### `stop`

```
sandscale.sandboxes.stop(sandbox_id: str, *, region: Optional[str]=None) -> None
```

Stops the sandbox and releases it.

### `pause`

```
sandscale.sandboxes.pause(sandbox_id: str, *, region: Optional[str]=None) -> Raw
```

Pauses a microVM sandbox (409 pause_unsupported for a container sandbox).

### `resume`

```
sandscale.sandboxes.resume(sandbox_id: str, *, region: Optional[str]=None) -> Raw
```

### `snapshot`

```
sandscale.sandboxes.snapshot(sandbox_id: str, *, label: Optional[str]=None, region: Optional[str]=None) -> Snapshot
```

Snapshots the sandbox's /workspace; start from it with ``create(snapshot_id=...)``.

### `list_snapshots`

```
sandscale.sandboxes.list_snapshots(sandbox_id: str, *, region: Optional[str]=None) -> List[Snapshot]
```

### `run`

```
sandscale.sandboxes.run(sandbox_id: str, command: Union[str, Sequence[str]], *, env: Optional[Mapping[str, str]]=None, workdir: Optional[str]=None, timeout: int=60, stdin: Union[bytes, str, None]=None, on_stdout: Optional[Callback]=None, on_stderr: Optional[Callback]=None, region: Optional[str]=None) -> RunResult
```

Runs a command and returns its exit code and output.

### `logs`

```
sandscale.sandboxes.logs(sandbox_id: str, run_id: str, *, from_chunk: Optional[int]=None, region: Optional[str]=None, on_done: Optional[Callable[[RunEnd], None]]=None) -> Iterator[OutputChunk]
```

Streams a run's output (Server-Sent Events), resuming after a dropped connection. ``on_done`` receives how the run ended, from the stream's done event.

### `write_file`

```
sandscale.sandboxes.write_file(sandbox_id: str, path: str, data: Union[bytes, str], *, mode: Optional[str]=None, region: Optional[str]=None) -> None
```

### `read_file`

```
sandscale.sandboxes.read_file(sandbox_id: str, path: str, *, region: Optional[str]=None) -> bytes
```

### `list_files`

```
sandscale.sandboxes.list_files(sandbox_id: str, path: str, *, region: Optional[str]=None) -> List[FileEntry]
```

## `sandscale.workspaces`

### `list`

```
sandscale.workspaces.list(*, limit: Optional[int]=None, cursor: Optional[str]=None, all: bool=False, region: Optional[str]=None) -> ListResult[Workspace]
```

Lists workspaces: of one region when one is named, else of every live region.

### `get`

```
sandscale.workspaces.get(workspace_id: str, *, region: Optional[str]=None) -> Workspace
```

### `start`

```
sandscale.workspaces.start(workspace_id: str, *, region: Optional[str]=None) -> WorkspaceBuild
```

Queues a start build.

### `stop`

```
sandscale.workspaces.stop(workspace_id: str, *, region: Optional[str]=None) -> WorkspaceBuild
```

Queues a stop build.

### `connect_info`

```
sandscale.workspaces.connect_info(workspace_id: str, *, region: Optional[str]=None) -> ConnectInfo
```

SSH host and command, port forwarding and editor links, as the server allows.

## `sandscale.build_hosts`

### `list_pools`

```
sandscale.build_hosts.list_pools(*, region: Optional[str]=None) -> ListResult[Pool]
```

### `list`

```
sandscale.build_hosts.list(*, scope: Optional[str]=None, state: Optional[str]=None, limit: Optional[int]=None, region: Optional[str]=None) -> ListResult[Lease]
```

The caller's leases (``scope="org"`` for every lease, where the server allows it).

### `get`

```
sandscale.build_hosts.get(lease_id: str, *, region: Optional[str]=None) -> Lease
```

### `start`

```
sandscale.build_hosts.start(pool_id: str, *, size: Optional[str]=None, ttl_seconds: Optional[int]=None, purpose: Optional[str]=None, repo: Optional[str]=None, region: Optional[str]=None) -> Lease
```

Takes a build host lease from a pool (it may wait for approval: ``pending_approval``).

### `stop`

```
sandscale.build_hosts.stop(lease_id: str, *, region: Optional[str]=None) -> Lease
```

Releases the lease; the server wipes and deletes its host.

### `connect_info`

```
sandscale.build_hosts.connect_info(lease_id: str, *, region: Optional[str]=None) -> LeaseConnectInfo
```

How to reach the lease's host: its workspace's connect info, or a lab host's SSH relay.

### `ssh_certificate`

```
sandscale.build_hosts.ssh_certificate(lease_id: str, public_key: str, *, region: Optional[str]=None) -> SSHCertificate
```

A short-lived SSH certificate for the lease's host, for your public key.

## Types

### FileEntry

| Field | Type | Description |
| --- | --- | --- |
| `name` | `str` |   |
| `path` | `str` |   |
| `is_dir` | `bool` |   |
| `size` optional | `Optional[int]` |   |

### LeaseConnectInfo

| Field | Type | Description |
| --- | --- | --- |
| `lease` | `Lease` |   |
| `kind` | `str` |   |
| `workspace` optional | `Optional[ConnectInfo]` |   |
| `ssh_relay_path` optional | `Optional[str]` |   |
| `ssh_user` optional | `Optional[str]` |   |

### ListResult

| Field | Type | Description |
| --- | --- | --- |
| `data` optional | `list[T]` |   |
| `pages` optional | `list[RegionPage]` |   |

### OutputChunk

| Field | Type | Description |
| --- | --- | --- |
| `stream` | `str` |   |
| `data` | `str` |   |
| `chunk_index` | `int` |   |

### RegionPage

One region's page of a list; lists without a region read every live region.

| Field | Type | Description |
| --- | --- | --- |
| `region` | `Optional[str]` |   |
| `has_more` optional | `bool` |   |
| `next_cursor` optional | `Optional[str]` |   |
| `error` optional | `Optional[SandscaleError]` |   |

### RunResult

| Field | Type | Description |
| --- | --- | --- |
| `run_id` | `str` |   |
| `exit_code` | `int` |   |
| `stdout` | `str` |   |
| `stderr` | `str` |   |
| `duration_ms` optional | `int` |   |
| `oom_killed` optional | `bool` |   |
| `timed_out` optional | `bool` |   |
| `streamed` optional | `bool` |   |

### SSHCertificate

| Field | Type | Description |
| --- | --- | --- |
| `certificate` | `str` |   |
| `serial` | `str` |   |
| `key_id` | `str` |   |
| `principals` | `list[str]` |   |
| `ssh` | `Raw` |   |
| `valid_after` optional | `Optional[datetime]` |   |
| `valid_before` optional | `Optional[datetime]` |   |

### VaultEnvRef

One Vault value of a sandbox's environment: variable ``name`` gets ``field`` of the secret at ``path``.

| Field | Type | Description |
| --- | --- | --- |
| `name` | `str` |   |
| `path` | `str` |   |
| `field` | `str` |   |

This page is generated from the SDK source (sdk/python/sandscale). Do not edit it by hand.

---
Source: https://sandscale.dev/docs/sdks/python
