> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Session
> サンドボックスのライフサイクルを管理し、関数の実行機能を提供します。
ソース: [src/cwsandbox/\_session.py:49](https://github.com/coreweave/cwsandbox-client/blob/v1.14.2/src/cwsandbox/_session.py#L49)
```python theme={"system"}
class Session(defaults: SandboxDefaults | Mapping[str, Any] | None = None, report_to: list[str] | None = None, *, auth: AuthConfig | None = None)
```
サンドボックスのライフサイクルを管理し、関数の実行機能を提供します。
次の場合にセッションを使用します。
* 共通の設定で複数のサンドボックスを作成する場合
* サンドボックスで Python 関数を実行する場合
* 孤立したサンドボックスを自動的にクリーンアップしたい場合
このセッションに関連付けられたサンドボックスで exec() が完了すると、
メトリクスが自動的に追跡されます。特定のトレーニングステップでメトリクスをログするには、
log\_metrics(step=N) を使用します。
プロパティ
sandbox\_count
```python theme={"system"}
@property
def sandbox_count(self) -> int
```
このセッションで現在追跡されているサンドボックスの数です。
メソッド
log\_metrics
```python theme={"system"}
log_metrics(step: int | None = None, *, reset: bool = True) -> bool
```
蓄積されたサンドボックスのメトリクスを wandb にログします。
トレーニング中にこのメソッドを呼び出すと、サンドボックスの使用状況をトレーニングステップに関連付けられます。
メトリクスは exec() の完了時に自動的に追跡されるため、
log\_metrics() を呼び出す必要があるのはステップとの関連付けを行う場合のみです。
メトリクスはセッションのクローズ時にも自動的にログされます。
**パラメーター**
* `step` (`int | None`): メトリクスに関連付けるトレーニングステップ。指定した場合、メトリクスは wandb 上でこのステップ番号にログされます。
* `reset` (`bool`): True (デフォルト) の場合、ログに成功した後、蓄積されたメトリクスをリセットします。log() が失敗した場合 (実行中の wandb run がない場合) は、メトリクスは保持されます。False に設定すると、ログの成否にかかわらず蓄積を継続します。
**戻り値**
* `bool`: メトリクスがログされた場合は True、レポーターが設定されていない場合は False
* `bool`: または実行中の wandb run がない場合。
**サンプル**
```python theme={"system"}
with Session(defaults, report_to=["wandb"]) as session:
for step in range(100):
sb = session.sandbox(...)
result = sb.exec(...).result() # メトリクスを自動的に追跡します
session.log_metrics(step=step) # 各 step でログします
```
get\_metrics
```python theme={"system"}
get_metrics() -> dict[str, Any]
```
現在蓄積されているメトリクスを取得します。
**戻り値**
* `dict[str, Any]`: cwsandbox/\* 接頭辞付きのメトリクス名と値を含む辞書。
* `dict[str, Any]`: レポーター が設定されていない場合は空の dict。
close
```python theme={"system"}
close() -> OperationRef[None]
```
管理対象のすべてのサンドボックスを停止し、OperationRef を即座に返します。
**戻り値**
* `OperationRef[None]`: OperationRef\[None]: .result() を使用すると、すべてのサンドボックスが停止するまでブロックします。
**送出される例外**
* `SandboxError`: 実行中のサンドボックスが 1 つ以上停止に失敗した場合。
**サンプル**
```python theme={"system"}
session.close().result() # すべてのサンドボックスが停止するまで待機します
```
sandbox
```python theme={"system"}
sandbox(*, command: str | None = None, args: list[str] | None = None, container_image: str | None = None, tags: list[str] | None = None, runner_ids: list[str] | None = None, resources: ResourceOptions | dict[str, Any] | None = None, mounted_files: list[dict[str, Any]] | None = None, network: NetworkOptions | dict[str, Any] | None = None, services: list[Service] | tuple[Service, ...] | None = None, volumes: list[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any]] | tuple[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any], ...] | None = None, file_system_snapshot: FileSystemSnapshotOptions | dict[str, Any] | None = None, placement_mode: PlacementMode | str | None = None, placement_spillover: PlacementSpillover | str | None = None, template_id: str | None = None, image_pull_credentials: ImagePullCredentials | dict[str, Any] | None = None, runtime_class: str | None = None, security_context: SecurityContext | dict[str, Any] | None = None, working_dir: str | None = None, object_storage_access: ObjectStorageAccess | dict[str, Any] | None = None, environment_variables: dict[str, str] | None = None, annotations: dict[str, str] | None = None, secrets: Sequence[Secret | dict[str, Any]] | None = None, request_timeout_seconds: float | None = None, data_plane_mode: DataPlaneMode | str | None = None, auth: AuthConfig | None = None, containers: Sequence[Container | Mapping[str, Any]] | None = None, **kwargs: Any = {}) -> Sandbox
```
セッションのデフォルト設定で、未起動のサンドボックスを作成します。
ネットワーク呼び出しは行わず、すぐに制御を返します。サンドボックスは
最初の操作 (exec、read\_file、write\_file、
wait) の実行時に自動的に起動します。start().result() で明示的に起動することもできます。
**パラメーター**
* `command` (`str | None`): サンドボックスで実行するコマンド
* `args` (`list[str] | None`): コマンドの引数
* `container_image` (`str | None`): 使用するコンテナーイメージ
* `tags` (`list[str] | None`): サンドボックスのタグ (`template_id` が設定されている場合もセッションのデフォルトとマージされ、`list()`/`adopt` でサンドボックスを検索できます) 。テンプレートを使用する場合 (テンプレートが所有する spec) 、環境変数とアノテーションはマージされません。
* `profile_ids`: 1.x で削除されました。値を渡すと `TypeError` が送出されます。
* `profile_names`: 1.x で削除されました。値を渡すと `TypeError` が送出されます。
* `runner_ids` (`list[str] | None`): オプションの CKS ランナー固定指定 (サーバーレスおよび `placement_spillover='serverless_then_cks'` とは併用できません)
* `resources` (`ResourceOptions | dict[str, Any] | None`): リソース設定。リクエストと制限を個別に指定する ResourceOptions、または後方互換性のある Guaranteed QoS 用のフラットな dict を受け入れます。
* `mounted_files` (`list[dict[str, Any]] | None`): 起動時にサンドボックスにマウントするファイル。各 dict には `mount_path` (str) と `file_content` (bytes) が必要です。注: マウントされたファイルは実行時に読み取り専用です。ファイルを変更するには、サンドボックスの実行開始後に `sandbox.write_file()` を使用します。
* `s3_mount`: 1.x で削除されました。値を渡すと `TypeError` が送出されます。
* `ports`: 1.x で削除されました。代わりに `services=[Service(...)]` を使用します。
* `network` (`NetworkOptions | dict[str, Any] | None`): 拒否フラグと、作成時に指定するオプションのホスト名グラントを含む `NetworkOptions` (または dict) 。ポートの公開には `services=` を使用します。
* `file_system_snapshot` (`FileSystemSnapshotOptions | dict[str, Any] | None`): 単一マウントを簡便に指定する FSS オプション (`FileSystemSnapshotOptions` または dict) 。複数ボリュームの構成には `volumes=` を推奨します。
* `max_timeout_seconds`: 1.x で削除されました。`request_timeout_seconds` を使用します。
* `request_timeout_seconds` (`float | None`): サンドボックス RPC のクライアント側 HTTP タイムアウト。デフォルトはセッションの `SandboxDefaults.request_timeout_seconds` です。
* `data_plane_mode` (`DataPlaneMode | str | None`): セッションのデータプレーンのトランスポートポリシーを上書きします。
* `auth` (`AuthConfig | None`): 認証方式、解決済みのヘッダー、またはプロバイダー。このサンドボックスについてセッションのデフォルトを上書きします。
* `environment_variables` (`dict[str, str] | None`): サンドボックスに注入する環境変数。セッションのデフォルトとマージされ、一致するキーを上書きします。機密性のない設定にのみ使用してください。
* `annotations` (`dict[str, str] | None`): サンドボックスの Kubernetes Pod アノテーション。セッションのデフォルトとマージされ、一致するキーを上書きします。機密性のないメタデータにのみ使用してください。
* `secrets` (`Sequence[Secret | dict[str, Any]] | None`): 環境変数として注入するシークレット。セッションのデフォルトとマージされます (デフォルトが先、このリストが後) 。
* `containers` (`Sequence[Container | Mapping[str, Any]] | None`): 複数コンテナーの spec。単一コンテナーのキーワード引数とは相互に排他的です。セッションの `defaults.secrets`、`environment_variables`、`security_context`、`working_dir` を置き換えます。これらは各 `Container` に設定してください。`@session.function()` では使用されません。
**戻り値**
* `Sandbox`: セッションに登録された、未起動の Sandbox。
**送出される例外**
* `SandboxError`: セッションが閉じられている場合。
**サンプル**
```python theme={"system"}
with Session(defaults) as session:
# 自動起動: 最初の exec() 呼び出しでサンドボックスが起動します
sb = session.sandbox(command="sleep", args=["infinity"])
result = sb.exec(["echo", "hello"]).result()
# 起動タイミングを制御するために明示的に起動します
sb2 = session.sandbox(command="sleep", args=["infinity"])
sb2.start().result()
sb2.wait()
result = sb2.exec(["echo", "hello"]).result()
```
list
```python theme={"system"}
list(*, tags: list[str] | None = None, status: str | None = None, profile_ids: list[str] | None = None, profile_names: list[str] | None = None, runner_ids: list[str] | None = None, show_terminated: bool = False, adopt: bool = False, volume_ids: list[str] | tuple[str, ...] | None = None) -> OperationRef[list[Sandbox]]
```
サンドボックスを一覧表示し、必要に応じてこのセッションに取り込みます。
セッションのデフォルトのタグがフィルターに自動的に含まれます。
これにより、このセッションまたは
同じデフォルトを使用する以前の run で作成されたサンドボックスを簡単に検索できます。
デフォルトでは、アクティブ (非終端状態) なサンドボックスのみが返されます。
`show_terminated=True` を設定すると、検索範囲が広がり、終端状態の
サンドボックス (完了、失敗、終了) も含まれます。
終端ステータスのフィルター (例：`status="completed"`) も、
検索範囲を自動的に広げます。
**パラメーター**
* `tags` (`list[str] | None`): フィルターに使用する追加のタグ (セッションのデフォルトのタグと統合されます)
* `status` (`str | None`): ステータスでフィルターします
* `profile_ids` (`list[str] | None`): 1.x で削除されました。値を渡すと `TypeError` が送出されます。
* `profile_names` (`list[str] | None`): 1.x で削除されました。値を渡すと `TypeError` が送出されます。
* `runner_ids` (`list[str] | None`): ランナー ID でフィルターします (セッションの runner\_ids が設定されている場合は、それがデフォルトになります)
* `volume_ids` (`list[str] | tuple[str, ...] | None`): これらの登録済み Volume ID に関連付けられたサンドボックスに絞り込みます
* `show_terminated` (`bool`): True の場合、終端状態のサンドボックス (完了、失敗、終了) を含めます。デフォルトは False です。
* `adopt` (`bool`): True の場合、検索されたサンドボックスをこのセッションに登録し、セッションが閉じられたときに停止されるようにします
**戻り値**
* `OperationRef[list[Sandbox]]`: OperationRef\[list\[Sandbox]]: .result() を使用して、結果が得られるまでブロックします。
* `OperationRef[list[Sandbox]]`: または、Asyncコンテキストで直接 await します。
**サンプル**
```python theme={"system"}
# セッションのデフォルトには、このアプリケーション/run 用のタグが含まれます
defaults = SandboxDefaults(tags=("my-app", "run-abc123"))
with Session(defaults) as session:
# 同期での使用例 - ["my-app", "run-abc123"] で自動的にフィルターします
orphans = session.list(adopt=True).result()
# フィルターを追加できます
running = session.list(status="running").result()
# クリーンアップや監査のために、停止したサンドボックスを含めます
all_sandboxes = session.list(show_terminated=True).result()
# Async の使用例
async with Session(defaults) as session:
orphans = await session.list(adopt=True)
```
from\_id
```python theme={"system"}
from_id(sandbox_id: str, *, adopt: bool = True) -> OperationRef[Sandbox]
```
既存のサンドボックスに接続し、必要に応じてこのセッションに取り込みます。
**パラメーター**
* `sandbox_id` (`str`): 既存のサンドボックスの ID
* `adopt` (`bool`): True (デフォルト) の場合、サンドボックスをこのセッションに登録します
**戻り値**
* `OperationRef[Sandbox]`: OperationRef\[Sandbox]: .result() を使用して Sandbox インスタンスが得られるまでブロックします。
* `OperationRef[Sandbox]`: または、Asyncコンテキストで直接 await します。
**サンプル**
```python theme={"system"}
with Session(defaults) as session:
# 同期での使用例 - サンドボックスに再接続します
sb = session.from_id("sandbox-abc123").result()
result = sb.exec(["echo", "hello"]).result()
# セッション終了時に sb は停止します
# Async の使用例
async with Session(defaults) as session:
sb = await session.from_id("sandbox-abc123")
result = await sb.exec(["echo", "hello"])
```
adopt
```python theme={"system"}
adopt(sandbox: Sandbox) -> None
```
既存の Sandbox インスタンスをこのセッションに取り込み、クリーンアップをトラッキングします。
Sandbox.list() または Sandbox.from\_id() で取得した Sandbox を、
セッション終了時に自動的に停止させたい場合に使用します。
**パラメーター**
* `sandbox` (`Sandbox`): トラッキングする Sandbox インスタンス
**送出される例外**
* `SandboxError`: セッションが終了している場合
* `ValueError`: サンドボックスに sandbox\_id がない場合
**サンプル**
```python theme={"system"}
with Session(defaults) as session:
# クラスメソッドでサンドボックスを取得します
sandboxes = Sandbox.list(tags=["my-job"]).result()
# サンドボックスをセッションに取り込みます
for sb in sandboxes:
session.adopt(sb)
# これでセッションが閉じるとサンドボックスが停止します
```
function
```python theme={"system"}
function(*, container_image: str | None = None, temp_dir: str | None = None, runner_ids: list[str] | None = None, resources: ResourceOptions | dict[str, Any] | None = None, mounted_files: Sequence[dict[str, Any]] | None = None, network: NetworkOptions | dict[str, Any] | None = None, services: Sequence[Service] | None = None, volumes: Sequence[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any]] | None = None, file_system_snapshot: FileSystemSnapshotOptions | dict[str, Any] | None = None, placement_mode: PlacementMode | str | None = None, placement_spillover: PlacementSpillover | str | None = None, runtime_class: str | None = None, security_context: SecurityContext | dict[str, Any] | None = None, working_dir: str | None = None, object_storage_access: ObjectStorageAccess | dict[str, Any] | None = None, environment_variables: dict[str, str] | None = None, annotations: dict[str, str] | None = None, request_timeout_seconds: float | None = None, data_plane_mode: DataPlaneMode | str | None = None, **kwargs: Any = {}) -> Callable[[Callable[P, R]], RemoteFunction[P, R]]
```
Python 関数をサンドボックスで実行するデコレーターです。
関数を呼び出すたびにエフェメラルなサンドボックスを作成し、関数を実行して、
結果を返します。サンドボックスは自動的にクリーンアップされます。
デコレーターを適用する関数は同期関数である必要があります。Async 関数はサポートされていません。
**パラメーター**
* `container_image` (`str | None`): この関数で使用するセッションのデフォルトイメージを上書きします
* `temp_dir` (`str | None`): サンドボックス内のペイロード/結果ファイル用の一時ディレクトリを上書きします。デフォルトはセッションのデフォルトです。存在しない場合は作成されます。
* `profile_ids`: 1.x で削除されました。値を渡すと `TypeError` が送出されます。
* `profile_names`: 1.x で削除されました。値を渡すと `TypeError` が送出されます。
* `runner_ids` (`list[str] | None`): 任意の CKS ランナー固定指定です (サーバーレスおよび `placement_spillover='serverless_then_cks'` とは併用できません)
* `resources` (`ResourceOptions | dict[str, Any] | None`): リソース設定です。リクエストと制限を個別に指定する ResourceOptions、または後方互換の Guaranteed QoS 用のフラットな dict を受け入れます。
* `mounted_files` (`Sequence[dict[str, Any]] | None`): 起動時にサンドボックスにマウントするファイルです。各 dict には `mount_path` (str) と `file_content` (bytes) が必要です。注: マウントされたファイルは実行時には読み取り専用です。ファイルを変更するには、サンドボックスの稼働後に `sandbox.write_file()` を使用してください。
* `s3_mount`: 1.x で削除されました。値を渡すと `TypeError` が送出されます。
* `ports`: 1.x で削除されました。代わりに `services=[Service(...)]` を使用してください。
* `network` (`NetworkOptions | dict[str, Any] | None`): 拒否フラグと、任意の作成時ホスト名グラントを指定する `NetworkOptions` (または dict) です。ポートの公開には `services=` を使用します。
* `file_system_snapshot` (`FileSystemSnapshotOptions | dict[str, Any] | None`): 単一マウント用の簡易 FSS オプション (`FileSystemSnapshotOptions` または dict) です。複数ボリュームの構成では `volumes=` を推奨します。
* `max_timeout_seconds`: 1.x で削除されました。`request_timeout_seconds` を使用してください。
* `request_timeout_seconds` (`float | None`): サンドボックス RPC 用のクライアント側 HTTP タイムアウトです。デフォルトはセッションの `SandboxDefaults.request_timeout_seconds` です。
* `data_plane_mode` (`DataPlaneMode | str | None`): セッションのデータプレーンのトランスポートポリシーを上書きします。
* `environment_variables` (`dict[str, str] | None`): サンドボックスに注入する環境変数です。セッションのデフォルトとマージされ、一致するキーを上書きします。機密性のない設定にのみ使用してください。
* `annotations` (`dict[str, str] | None`): サンドボックスの Kubernetes Pod アノテーションです。セッションのデフォルトとマージされ、一致するキーを上書きします。機密性のないメタデータにのみ使用してください。
**戻り値**
* `Callable[[Callable[P, R]], RemoteFunction[P, R]]`: 関数を RemoteFunction としてラップするデコレーターです
**サンプル**
```python theme={"system"}
with Session(defaults) as session:
@session.function()
def compute(x: int, y: int) -> int:
return x + y
# .remote() を呼び出してサンドボックスで実行する
ref = compute.remote(2, 3) # OperationRef をすぐに返す
result = ref.result() # 結果をブロックする
print(result) # 5
# または async コンテキストで await を使用する
result = await compute.remote(2, 3)
# テストのためにローカルで実行する
result = compute.local(2, 3)
# 複数の入力を並列にマップする
refs = compute.map([(1, 2), (3, 4), (5, 6)])
results = [ref.result() for ref in refs]
```