> ## 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.

# Sessions

> Regroupez et gérez plusieurs bacs à sable à l’aide des sessions.

Ces exemples utilisent un jeton d’accès à l’API CoreWeave défini dans `CWSANDBOX_API_KEY`. Pour l’authentification par clé API Forge, consultez [Premiers pas](/fr/products/sandboxes/get-started). Pour connaître les exigences relatives à CKS, consultez [Modes de placement](/fr/products/sandboxes/placement).

Ce guide explique comment utiliser `Session` pour gérer plusieurs bacs à sable avec une configuration partagée. Il s’adresse aux développeurs côté client qui doivent coordonner des groupes de bacs à sable, appliquer des valeurs par défaut communes et garantir un nettoyage cohérent à l’échelle d’une charge de travail.

<h2 id="session-overview">
  Aperçu de la session
</h2>

Une `Session` fournit :

* Une configuration par défaut commune à tous les bacs à sable.
* Un nettoyage automatique à la fermeture de la session.
* Une portée pour le décorateur `@session.function()`.

<h2 id="basic-usage">
  Utilisation de base
</h2>

```python theme={"system"}
import cwsandbox
from cwsandbox import SandboxDefaults

# Définir une configuration partagée
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("project-alpha",),
)

# Créer une session à l’aide d’un gestionnaire de contexte
with cwsandbox.Session(defaults=defaults) as session:
    # Créer des bacs à sable via la session
    sb1 = session.sandbox()
    sb2 = session.sandbox()

    # Utiliser les bacs à sable
    result1 = sb1.exec(["echo", "sandbox 1"]).result()
    result2 = sb2.exec(["echo", "sandbox 2"]).result()

# Tous les bacs à sable sont automatiquement arrêtés à la sortie du contexte
```

<h2 id="create-sandboxes">
  Créer des bacs à sable
</h2>

Les sections suivantes expliquent comment créer des bacs à sable à partir d’une session et comment remplacer les valeurs par défaut de la session.

<h3 id="sessionsandbox">
  session.sandbox()
</h3>

Crée une sandbox avec les valeurs par défaut de la session. La sandbox ne démarre qu'à sa première utilisation :

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    # sandbox() renvoie une sandbox non démarrée
    sandbox = session.sandbox()

    # Toute opération démarre automatiquement la sandbox à la première utilisation
    result = sandbox.exec(["echo", "hello"]).result()
```

Pour contrôler explicitement le moment où le RPC de démarrage est déclenché :

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    sandbox = session.sandbox()
    sandbox.start().result()  # Démarrage explicite
    sandbox.wait()            # Attendre l’état RUNNING
    result = sandbox.exec(["echo", "hello"]).result()
```

<h3 id="override-defaults">
  Remplacer les valeurs par défaut
</h3>

Transmettez des arguments supplémentaires pour remplacer les valeurs par défaut de la session :

```python theme={"system"}
from cwsandbox import ResourceOptions

# Session avec la configuration de base
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project",),
)

with cwsandbox.Session(defaults=defaults) as session:
    # Remplacer l’image et les ressources pour cette sandbox
    gpu_sandbox = session.sandbox(
        command="sleep",
        args=["infinity"],
        container_image="pytorch/pytorch:latest",
        resources=ResourceOptions(
            requests={"cpu": "4", "memory": "16Gi"},
            limits={"cpu": "8", "memory": "32Gi"},
            gpu={"count": 1},
        ),
        tags=["gpu-workload"],  # Fusionnés avec les tags de la session
    )
```

Consultez le [guide de configuration du bac à sable](/fr/products/sandboxes/client/guides/sandbox-configuration) pour connaître toutes les options disponibles.

<h2 id="multiple-sandbox-management">
  Gestion de sandboxes multiples
</h2>

Les sessions se prêtent bien à la gestion de pools de sandboxes :

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    # Créer un pool de bacs à sable
    sandboxes = [
        session.sandbox()
        for _ in range(5)
    ]

    # Répartir le travail entre les sandboxes du pool
    processes = [
        sb.exec(["python", "-c", f"print({i})"])
        for i, sb in enumerate(sandboxes)
    ]

    # Collecter les résultats
    results = [p.result() for p in processes]

# Les 5 bacs à sable sont nettoyés automatiquement
```

Pour préparer des bacs à sable avant l’arrivée des requêtes, voir
[Implement a warm pool](/fr/products/sandboxes/warm-pools).
La recette maintient une réserve de bacs à sable prêts, attribue à chaque charge de travail un
sandbox distinct et réalimente la réserve à mesure que les charges de travail les prennent.

<h2 id="session-lifecycle">
  Cycle de vie de la session
</h2>

Les sections suivantes expliquent comment fermer une session, ce que fait `close()` et comment gérer les erreurs.

<h3 id="manual-close">
  Fermeture manuelle
</h3>

Si vous n'utilisez pas de gestionnaire de contexte, fermez explicitement la session :

```python theme={"system"}
session = cwsandbox.Session(defaults=defaults)

sandbox = session.sandbox()
result = sandbox.exec(["echo", "hello"]).result()

# Fermer la session (arrête toutes les sandboxes)
session.close().result()
```

<h3 id="what-close-does">
  Ce que fait close()
</h3>

L’appel à `close()` effectue les actions suivantes :

1. Arrête tous les bacs à sable créés via la session ou adoptés par celle-ci.
2. Attend la fin du nettoyage.
3. Renvoie `OperationRef[None]`.

<h3 id="error-handling">
  Gestion des erreurs
</h3>

Les sessions sont nettoyées même si des exceptions se produisent :

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    sandbox = session.sandbox()
    raise RuntimeError("Something went wrong!")
# Le sandbox est tout de même nettoyé
```

<h2 id="adopt-external-sandboxes">
  Adopter des bacs à sable externes
</h2>

Confiez à la session la gestion des bacs à sable créés en dehors de celle-ci :

```python theme={"system"}
import cwsandbox
from cwsandbox import Sandbox

with cwsandbox.Session(defaults=defaults) as session:
    # Trouver les sandboxes existants
    existing = Sandbox.list(tags=["orphaned-work"]).result()

    # Les adopter pour qu'ils soient nettoyés
    for sandbox in existing:
        session.adopt(sandbox)

    # session.close() les nettoiera désormais eux aussi
```

<h2 id="session-properties">
  Propriétés de Session
</h2>

Consultez l’état de la session grâce aux propriétés intégrées, telles que `sandbox_count` :

```python theme={"system"}
session = cwsandbox.Session(defaults=defaults)

# Nombre de bacs à sable suivis
print(session.sandbox_count)  # 0

sandbox = session.sandbox()
print(session.sandbox_count)  # 1
```

<h2 id="when-to-use-sessions">
  Quand utiliser les sessions
</h2>

| Cas d’utilisation | Approche recommandée |
| - | - |
| Sandbox unique, tâche simple | `Sandbox.run()` avec un gestionnaire de contexte |
| Plusieurs bacs à sable, configuration partagée | Session |
| API de décorateurs de fonctions | Session requise |
| Pool de workers | Session |
| Commande ponctuelle | Appel direct à `Sandbox.run()` |

<h2 id="without-sessions">
  Sans sessions
</h2>

Les sessions ne sont pas nécessaires pour une sandbox unique :

```python theme={"system"}
from cwsandbox import Sandbox

# Utilisation directe sans session
with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# Nettoyage géré par le gestionnaire de contexte
```