Session

class Session(defaults: SandboxDefaults | Mapping[str, Any] | None = None, report_to: list[str] | None = None, *, auth: AuthConfig | None = None)

• Création de plusieurs sandboxes partageant une même configuration
• Exécution de fonctions Python dans des sandboxes
• Nettoyage automatique des sandboxes orphelins

​

Propriétés

​

sandbox_count

@property
def sandbox_count(self) -> int

​

Méthodes

​

log_metrics

log_metrics(step: int | None = None, *, reset: bool = True) -> bool

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

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

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

get_metrics() -> dict[str, Any]

• 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

close() -> OperationRef[None]

• OperationRef[None] : OperationRef[None] : utilisez .result() pour bloquer l’exécution jusqu’à l’arrêt de tous les sandboxes.

• SandboxError : si un ou plusieurs sandboxes en cours d’exécution n’ont pas pu être arrêtés.

session.close().result()  # Bloque jusqu'à l'arrêt de tous les bacs à sable

​

sandbox

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

• 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().

• Sandbox : une Sandbox non démarrée, enregistrée auprès de la session.

• SandboxError : si la session a été fermée.

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

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]]

• 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

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

# 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

from_id(sandbox_id: str, *, adopt: bool = True) -> OperationRef[Sandbox]

• sandbox_id (str) : l’ID de la sandbox existante
• adopt (bool) : si True (par défaut), enregistre la sandbox auprès de cette session

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

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

adopt(sandbox: Sandbox) -> None

• sandbox (Sandbox) : instance Sandbox à suivre

• SandboxError : si la session est fermée
• ValueError : si la sandbox n’a pas de sandbox_id

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

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]]

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

• Callable[[Callable[P, R]], RemoteFunction[P, R]] : un décorateur qui encapsule une fonction dans une RemoteFunction

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]