> ## 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
> Gère le cycle de vie des sandboxes et permet d’exécuter des fonctions.
Source : [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)
```
Gère le cycle de vie des sandboxes et permet d’exécuter des fonctions.
Utilisez une session dans les cas suivants :
* Création de plusieurs sandboxes partageant une même configuration
* Exécution de fonctions Python dans des sandboxes
* Nettoyage automatique des sandboxes orphelins
Les métriques sont automatiquement suivies lorsque l’appel exec() se termine sur n’importe quel sandbox
associé à cette session. Utilisez log\_metrics(step=N) pour consigner des métriques
à des étapes d’entraînement précises.
Propriétés
sandbox\_count
```python theme={"system"}
@property
def sandbox_count(self) -> int
```
Nombre de sandboxes actuellement suivis par cette session.
Méthodes
log\_metrics
```python theme={"system"}
log_metrics(step: int | None = None, *, reset: bool = True) -> bool
```
Journalise dans wandb les métriques de sandbox accumulées.
Appelez cette méthode pendant l’entraînement pour corréler l’utilisation de la sandbox avec les étapes d’entraînement.
Les métriques sont automatiquement suivies lorsque exec() se termine : les utilisateurs
n’ont donc besoin d’appeler log\_metrics() que pour la corrélation avec les étapes.
Les métriques sont également journalisées automatiquement à la fermeture de la session.
**Paramètres**
* `step` (`int | None`) : étape d’entraînement à associer aux métriques. Si cette valeur est fournie, les métriques sont journalisées à ce numéro de step dans wandb.
* `reset` (`bool`) : si True (par défaut), réinitialise les métriques accumulées après une journalisation réussie. Les métriques sont conservées en cas d’échec de log() (aucun run wandb actif). Définissez cette valeur sur False pour continuer à les accumuler dans tous les cas.
**Renvoie**
* `bool` : True si les métriques ont été journalisées, False si aucun reporter n’est configuré
* `bool` : ou s’il n’y a aucun run wandb actif.
**Exemples**
```python theme={"system"}
with Session(defaults, report_to=["wandb"]) as session:
for step in range(100):
sb = session.sandbox(...)
result = sb.exec(...).result() # Métriques suivies automatiquement
session.log_metrics(step=step) # Journaliser à chaque étape
```
get\_metrics
```python theme={"system"}
get_metrics() -> dict[str, Any]
```
Obtient les métriques actuellement cumulées.
**Renvoie**
* `dict[str, Any]` : dictionnaire contenant les noms des métriques, préfixés par cwsandbox/\*, et leurs valeurs.
* `dict[str, Any]` : dict vide si aucun reporter n’est configuré.
close
```python theme={"system"}
close() -> OperationRef[None]
```
Arrête tous les sandboxes managés et renvoie immédiatement un OperationRef.
**Renvoie**
* `OperationRef[None]` : OperationRef\[None] : utilisez .result() pour bloquer l’exécution jusqu’à l’arrêt de tous les sandboxes.
**Exceptions levées**
* `SandboxError` : si un ou plusieurs sandboxes en cours d’exécution n’ont pas pu être arrêtés.
**Exemples**
```python theme={"system"}
session.close().result() # Bloque jusqu'à l'arrêt de tous les bacs à sable
```
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
```
Crée une sandbox non démarrée avec les valeurs par défaut de la session.
Renvoie immédiatement, sans aucun appel réseau. La sandbox
démarre automatiquement lors de la première opération (exec, read\_file, write\_file,
wait), mais vous pouvez aussi la démarrer explicitement avec start().result().
**Paramètres**
* `command` (`str | None`) : commande à exécuter dans la sandbox
* `args` (`list[str] | None`) : arguments de la commande
* `container_image` (`str | None`) : image de conteneur à utiliser
* `tags` (`list[str] | None`) : tags de la sandbox (fusionnés avec les valeurs par défaut de la session, y compris lorsque `template_id` est défini, afin que `list()`/`adopt` puissent retrouver la sandbox). Les variables d’environnement et les annotations ne sont pas fusionnées lorsqu’un modèle est utilisé (la spécification relève du modèle).
* `profile_ids` : supprimé dans la version 1.x ; transmettre une valeur lève une `TypeError`.
* `profile_names` : supprimé dans la version 1.x ; transmettre une valeur lève une `TypeError`.
* `runner_ids` (`list[str] | None`) : épinglage facultatif sur un exécuteur CKS (incompatible avec le mode sans serveur et avec `placement_spillover='serverless_then_cks'`)
* `resources` (`ResourceOptions | dict[str, Any] | None`) : configuration des ressources. Accepte ResourceOptions pour distinguer demandes de ressources et limites, ou un dict plat pour une QoS Guaranteed rétrocompatible.
* `mounted_files` (`list[dict[str, Any]] | None`) : fichiers à monter dans la sandbox au démarrage. Chaque dict doit contenir `mount_path` (str) et `file_content` (bytes). Remarque : les fichiers montés sont en lecture seule à l’exécution. Pour modifier un fichier, utilisez `sandbox.write_file()` une fois la sandbox en cours d’exécution.
* `s3_mount` : supprimé dans la version 1.x ; transmettre une valeur lève une `TypeError`.
* `ports` : supprimé dans la version 1.x ; utilisez plutôt `services=[Service(...)]`.
* `network` (`NetworkOptions | dict[str, Any] | None`) : `NetworkOptions` (ou dict) avec des flags de refus et des autorisations facultatives de noms d’hôte accordées à la création. L’exposition des ports s’effectue via `services=`.
* `file_system_snapshot` (`FileSystemSnapshotOptions | dict[str, Any] | None`) : options FSS simplifiées pour un montage unique (`FileSystemSnapshotOptions` ou dict). Privilégiez `volumes=` pour les configurations à plusieurs volumes.
* `max_timeout_seconds` : supprimé dans la version 1.x ; utilisez `request_timeout_seconds`.
* `request_timeout_seconds` (`float | None`) : délai d’expiration HTTP côté client pour les RPC de la sandbox. Par défaut, `SandboxDefaults.request_timeout_seconds` de la session.
* `data_plane_mode` (`DataPlaneMode | str | None`) : remplace la politique de transport du plan de données de la session.
* `auth` (`AuthConfig | None`) : stratégie d’authentification, en-têtes résolus ou fournisseur. Remplace la valeur par défaut de la session pour cette sandbox.
* `environment_variables` (`dict[str, str] | None`) : variables d’environnement à injecter dans la sandbox. Fusionnées avec les valeurs par défaut de la session, dont elles remplacent les clés correspondantes. À réserver à une configuration non sensible.
* `annotations` (`dict[str, str] | None`) : annotations de pod Kubernetes pour la sandbox. Fusionnées avec les valeurs par défaut de la session, dont elles remplacent les clés correspondantes. À réserver à des métadonnées non sensibles.
* `secrets` (`Sequence[Secret | dict[str, Any]] | None`) : secrets à injecter sous forme de variables d’environnement. Fusionnés avec les valeurs par défaut de la session (valeurs par défaut d’abord, puis cette liste).
* `containers` (`Sequence[Container | Mapping[str, Any]] | None`) : spécification multiconteneur. Incompatible avec les kwargs monoconteneur. Remplace `defaults.secrets`, `environment_variables`, `security_context` et `working_dir` de la session ; définissez-les plutôt sur chaque `Container`. Non utilisé par `@session.function()`.
**Renvoie**
* `Sandbox` : une Sandbox non démarrée, enregistrée auprès de la session.
**Exceptions levées**
* `SandboxError` : si la session a été fermée.
**Exemples**
```python theme={"system"}
with Session(defaults) as session:
# Démarrage automatique : la sandbox démarre au premier appel à exec()
sb = session.sandbox(command="sleep", args=["infinity"])
result = sb.exec(["echo", "hello"]).result()
# Démarrage explicite pour maîtriser le moment du lancement
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]]
```
Liste les sandboxes et peut éventuellement les adopter dans cette session.
Inclut automatiquement les tags par défaut de la session dans le filtre.
Vous pouvez ainsi retrouver facilement les sandboxes créés par cette session ou
par un run précédent utilisant les mêmes valeurs par défaut.
Par défaut, seuls les sandboxes actifs (non terminaux) sont renvoyés.
Définissez `show_terminated=True` pour étendre la recherche aux sandboxes
terminaux (terminés, en échec, arrêtés définitivement).
Un filtre sur un statut terminal (par ex. `status="completed"`) étend également
la recherche automatiquement.
**Paramètres**
* `tags` (`list[str] | None`) : tags supplémentaires servant de filtre (fusionnés avec les tags par défaut de la session)
* `status` (`str | None`) : filtre par statut
* `profile_ids` (`list[str] | None`) : supprimé dans la version 1.x ; transmettre une valeur lève une `TypeError`.
* `profile_names` (`list[str] | None`) : supprimé dans la version 1.x ; transmettre une valeur lève une `TypeError`.
* `runner_ids` (`list[str] | None`) : filtre par ID d’exécuteurs (par défaut, runner\_ids de la session s’il est défini)
* `volume_ids` (`list[str] | tuple[str, ...] | None`) : limite aux sandboxes associés à ces ID de Volumes enregistrés
* `show_terminated` (`bool`) : si True, inclut les sandboxes terminaux (terminés, en échec, arrêtés définitivement). Par défaut : False.
* `adopt` (`bool`) : si True, enregistre les sandboxes découverts auprès de cette session afin qu’ils soient arrêtés à la fermeture de celle-ci
**Renvoie**
* `OperationRef[list[Sandbox]]` : OperationRef\[list\[Sandbox]] : utilisez .result() pour attendre les résultats de manière bloquante,
* `OperationRef[list[Sandbox]]` : ou utilisez directement await dans les contextes asynchrones.
**Exemples**
```python theme={"system"}
# Les valeurs par défaut de la session incluent une étiquette pour cette application/ce run
defaults = SandboxDefaults(tags=("my-app", "run-abc123"))
with Session(defaults) as session:
# Utilisation synchrone : filtre automatiquement par ["my-app", "run-abc123"]
orphans = session.list(adopt=True).result()
# Vous pouvez ajouter d’autres filtres
running = session.list(status="running").result()
# Inclure les sandboxes arrêtées à des fins de nettoyage ou d’audit
all_sandboxes = session.list(show_terminated=True).result()
# Utilisation asynchrone
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]
```
Se rattache à une sandbox existante, en l’adoptant éventuellement dans cette session.
**Paramètres**
* `sandbox_id` (`str`) : l’ID de la sandbox existante
* `adopt` (`bool`) : si True (par défaut), enregistre la sandbox auprès de cette session
**Renvoie**
* `OperationRef[Sandbox]` : OperationRef\[Sandbox] : utilisez .result() pour attendre de manière bloquante l’instance Sandbox,
* `OperationRef[Sandbox]` : ou utilisez directement await dans les contextes asynchrones.
**Exemples**
```python theme={"system"}
with Session(defaults) as session:
# Utilisation synchrone : se reconnecter à une sandbox
sb = session.from_id("sandbox-abc123").result()
result = sb.exec(["echo", "hello"]).result()
# sb est arrêtée à la fermeture de la session
# Utilisation asynchrone
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
```
Adopte une instance Sandbox existante dans cette session afin que son nettoyage soit suivi.
Utilisez cette méthode lorsque vous disposez d’une Sandbox obtenue via Sandbox.list() ou Sandbox.from\_id()
et que vous souhaitez qu’elle soit automatiquement arrêtée à la fermeture de la session.
**Paramètres**
* `sandbox` (`Sandbox`) : instance Sandbox à suivre
**Exceptions levées**
* `SandboxError` : si la session est fermée
* `ValueError` : si la sandbox n’a pas de sandbox\_id
**Exemples**
```python theme={"system"}
with Session(defaults) as session:
# Récupérer les sandboxes via une méthode de classe
sandboxes = Sandbox.list(tags=["my-job"]).result()
# Les adopter dans la session
for sb in sandboxes:
session.adopt(sb)
# Elles seront désormais arrêtées à la fermeture de la session
```
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]]
```
Décorateur permettant d’exécuter une fonction Python dans une sandbox.
Chaque appel de fonction crée une sandbox éphémère, exécute la fonction,
puis renvoie le résultat. La sandbox est automatiquement nettoyée.
La fonction décorée doit être synchrone. Les fonctions asynchrones ne sont pas prises en charge.
**Paramètres**
* `container_image` (`str | None`) : remplace l’image par défaut de la session pour cette fonction
* `temp_dir` (`str | None`) : remplace le répertoire temporaire utilisé dans la sandbox pour les fichiers de charge utile et de résultat. Utilise par défaut la valeur de la session. Créé s’il n’existe pas.
* `profile_ids` : supprimé dans la version 1.x ; transmettre une valeur lève une `TypeError`.
* `profile_names` : supprimé dans la version 1.x ; transmettre une valeur lève une `TypeError`.
* `runner_ids` (`list[str] | None`) : épinglage facultatif sur un exécuteur CKS (incompatible avec le mode sans serveur et avec `placement_spillover='serverless_then_cks'`)
* `resources` (`ResourceOptions | dict[str, Any] | None`) : configuration des ressources. Accepte un objet ResourceOptions pour définir séparément les demandes de ressources et les limites, ou un dict plat pour une QoS Guaranteed rétrocompatible.
* `mounted_files` (`Sequence[dict[str, Any]] | None`) : fichiers à monter dans la sandbox au démarrage. Chaque dict doit contenir `mount_path` (str) et `file_content` (bytes). Remarque : les fichiers montés sont en lecture seule à l’exécution. Pour modifier un fichier, utilisez `sandbox.write_file()` une fois la sandbox démarrée.
* `s3_mount` : supprimé dans la version 1.x ; transmettre une valeur lève une `TypeError`.
* `ports` : supprimé dans la version 1.x ; utilisez plutôt `services=[Service(...)]`.
* `network` (`NetworkOptions | dict[str, Any] | None`) : `NetworkOptions` (ou dict) contenant des flags de refus et, éventuellement, des autorisations de noms d’hôte accordées à la création. Pour exposer des ports, utilisez `services=`.
* `file_system_snapshot` (`FileSystemSnapshotOptions | dict[str, Any] | None`) : options FSS simplifiées pour un montage unique (`FileSystemSnapshotOptions` ou dict). Privilégiez `volumes=` pour les configurations à plusieurs volumes.
* `max_timeout_seconds` : supprimé dans la version 1.x ; utilisez `request_timeout_seconds`.
* `request_timeout_seconds` (`float | None`) : délai d’expiration HTTP côté client pour les RPC de la sandbox. Utilise par défaut la valeur `SandboxDefaults.request_timeout_seconds` de la session.
* `data_plane_mode` (`DataPlaneMode | str | None`) : remplace la politique de transport du plan de données définie pour la session.
* `environment_variables` (`dict[str, str] | None`) : variables d’environnement à injecter dans la sandbox. Elles sont fusionnées avec les valeurs par défaut de la session et remplacent les clés correspondantes. À réserver aux configurations non sensibles.
* `annotations` (`dict[str, str] | None`) : annotations de pod Kubernetes pour la sandbox. Elles sont fusionnées avec les valeurs par défaut de la session et remplacent les clés correspondantes. À réserver aux métadonnées non sensibles.
**Renvoie**
* `Callable[[Callable[P, R]], RemoteFunction[P, R]]` : un décorateur qui encapsule une fonction dans une RemoteFunction
**Exemples**
```python theme={"system"}
with Session(defaults) as session:
@session.function()
def compute(x: int, y: int) -> int:
return x + y
# Appeler .remote() pour exécuter dans la sandbox
ref = compute.remote(2, 3) # Renvoie OperationRef immédiatement
result = ref.result() # Bloque jusqu’à l’obtention du résultat
print(result) # 5
# Ou utiliser await dans un contexte asynchrone
result = await compute.remote(2, 3)
# Exécuter en local pour les tests
result = compute.local(2, 3)
# Appliquer à plusieurs entrées en parallèle
refs = compute.map([(1, 2), (3, 4), (5, 6)])
results = [ref.result() for ref in refs]
```