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

# Opérations sur les fichiers

> Lire, écrire et gérer des fichiers dans les instances de sandbox CoreWeave à l’aide du client CWSandbox

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 liées à CKS, consultez [Modes de placement](/fr/products/sandboxes/placement).

Ce guide explique comment lire, écrire et gérer des fichiers dans une instance de sandbox CoreWeave à l’aide du client CWSandbox. Il s’adresse aux développeurs qui conçoivent des flux de travail chargés de transférer des données vers et depuis des bacs à sable. Il aborde notamment les téléversements et téléchargements en parallèle, la gestion des erreurs et les bonnes pratiques pour les fichiers volumineux.

<h2 id="basic-operations">
  Opérations de base
</h2>

Les exemples de cette section présentent les opérations sur les fichiers les plus courantes : écrire des données dans un chemin de la sandbox, puis les relire. Les opérations sur les fichiers renvoient des objets `OperationRef`. Utilisez `.result()` pour bloquer l’exécution jusqu’à l’achèvement de l’opération.

<h3 id="write-files">
  Écrire des fichiers
</h3>

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

with Sandbox.run() as sandbox:
    # Écrire des octets dans un fichier
    sandbox.write_file("/app/data.txt", b"Hello, World!").result()

    # Écrire du JSON
    import json
    config = {"key": "value", "count": 42}
    sandbox.write_file(
        "/app/config.json",
        json.dumps(config).encode()
    ).result()
```

<h3 id="read-files">
  Lire des fichiers
</h3>

```python theme={"system"}
# Lire le contenu du fichier sous forme d’octets
content = sandbox.read_file("/app/data.txt").result()
print(content.decode())  # "Hello, World!"

# Lire un fichier JSON
config_bytes = sandbox.read_file("/app/config.json").result()
config = json.loads(config_bytes.decode())
```

<h2 id="parallel-operations">
  Opérations parallèles
</h2>

Les opérations sur les fichiers rendent la main immédiatement, ce qui permet naturellement de les paralléliser. Lorsque vous avez plusieurs fichiers indépendants, effectuer les téléversements ou les téléchargements en parallèle peut réduire la durée totale de transfert.

<h3 id="parallel-uploads">
  Téléversements parallèles
</h3>

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

# Lancer tous les téléversements simultanément
write_refs = [
    sandbox.write_file("/app/config.json", config_bytes),
    sandbox.write_file("/app/data.csv", data_bytes),
    sandbox.write_file("/app/model.pkl", model_bytes),
]

# Attendre la fin de tous les téléversements
results(write_refs)
```

<h3 id="parallel-downloads">
  Téléchargements parallèles
</h3>

```python theme={"system"}
# Lancer tous les téléchargements en parallèle
read_refs = [
    sandbox.read_file("/app/output.json"),
    sandbox.read_file("/app/metrics.json"),
    sandbox.read_file("/app/logs.txt"),
]

# Récupérer tous les résultats
output, metrics, logs = results(read_refs)
```

<h2 id="upload-process-download-pattern">
  Schéma téléversement-traitement-téléchargement
</h2>

Voici un flux de travail courant : téléverser les fichiers d’entrée, lancer le traitement, puis télécharger les résultats.

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

with Sandbox.run() as sandbox:
    # 1. Téléversements en parallèle
    results([
        sandbox.write_file("/app/config.json", config_bytes),
        sandbox.write_file("/app/input.csv", input_bytes),
    ])

    # 2. Traitement séquentiel
    sandbox.exec(["pip", "install", "-r", "requirements.txt"]).result()
    sandbox.exec(["python", "/app/process.py"]).result()

    # 3. Téléchargements en parallèle
    output, metrics = results([
        sandbox.read_file("/app/output.json"),
        sandbox.read_file("/app/metrics.json"),
    ])
```

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

Les opérations sur les fichiers peuvent échouer si un chemin n’existe pas ou n’est pas accessible en écriture. Interceptez `SandboxFileError` pour gérer ces cas et identifier le chemin concerné.

<h3 id="file-not-found">
  Fichier introuvable
</h3>

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

try:
    content = sandbox.read_file("/nonexistent/file.txt").result()
except SandboxFileError as e:
    print(f"File error: {e.filepath}")
```

<h3 id="write-errors">
  Erreurs d’écriture
</h3>

```python theme={"system"}
try:
    sandbox.write_file("/readonly/path.txt", b"data").result()
except SandboxFileError as e:
    print(f"Cannot write to: {e.filepath}")
```

<h2 id="binary-files">
  Fichiers binaires
</h2>

Les opérations sur les fichiers prennent en charge tout type de contenu binaire, y compris les images et les objets Python sérialisés :

```python theme={"system"}
# Images
with open("image.png", "rb") as f:
    sandbox.write_file("/app/image.png", f.read()).result()

# Fichiers pickle (ne désérialisez que des données provenant de sources fiables)
import pickle
model_bytes = pickle.dumps(my_model)
sandbox.write_file("/app/model.pkl", model_bytes).result()

# Téléchargement et désérialisation
model_bytes = sandbox.read_file("/app/trained_model.pkl").result()
trained_model = pickle.loads(model_bytes)
```

<Warning>
  Ne désérialisez avec pickle que des données provenant de sources de confiance. Le chargement d’un fichier pickle peut entraîner l’exécution de code arbitraire.
</Warning>

<h2 id="text-encoding">
  Encodage du texte
</h2>

Les fichiers sont transférés sous forme d’octets : vous devez donc encoder et décoder explicitement le texte pour éviter toute corruption des caractères non ASCII.

```python theme={"system"}
# Écrire du texte
text = "Hello, Unicode! "
sandbox.write_file("/app/text.txt", text.encode("utf-8")).result()

# Lire du texte
content = sandbox.read_file("/app/text.txt").result()
text = content.decode("utf-8")
```

<h2 id="large-file-considerations">
  Considérations relatives aux fichiers volumineux
</h2>

Les API `read_file` et `write_file` sont surtout adaptées aux fichiers de petite ou moyenne taille. Pour les fichiers volumineux, tenez compte des points suivants :

* Tenez compte de la bande passante, car les fichiers transitent par l’API.
* Dans la mesure du possible, utilisez la diffusion en continu pour les datasets volumineux.
* Accédez directement au stockage d’objets plutôt que de faire transiter les données par l’API.

Le paramètre `object_storage_access` crée des identifiants d’authentification CoreWeave AI Object Storage temporaires et les fournit aux conteneurs du sandbox. Votre charge de travail lit et écrit alors directement dans les buckets, si bien que les objets volumineux ne transitent jamais par `read_file` ni par `write_file`. Votre organisation doit au préalable enregistrer une configuration de fédération d’identités de charges de travail auprès du plan de contrôle des sandbox ; voir [Accès au stockage d’objets](/fr/products/sandboxes/operations/object-storage-access).

L’exemple suivant utilise l’authentification CoreWeave pour démarrer un sandbox avec un accès en lecture-écriture à un bucket, puis vérifie que les identifiants d’authentification ont bien été injectés. Définissez `CWSANDBOX_API_KEY` sur un jeton d’accès à l’API CoreWeave de l’organisation configurée, puis remplacez `[BUCKET-NAME]` par le nom de votre bucket :

```python theme={"system"}
from cwsandbox import AuthStrategy, ObjectStorageAccess, ObjectStoragePermission, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    container_image="python:3.11",
    object_storage_access=ObjectStorageAccess(
        buckets=["[BUCKET-NAME]"],
        permission=ObjectStoragePermission.READ_WRITE,
    ),
) as sandbox:
    result = sandbox.exec(["printenv", "AWS_ENDPOINT_URL_S3"]).result()
    print(result.stdout)
```

Le sandbox définit les variables d’environnement que les SDK AWS lisent pour obtenir les identifiants de conteneur, si bien que tout client compatible S3 exécuté à l’intérieur fonctionne sans clés explicites. Pour connaître ces variables et consulter un exemple Boto3, voir [Utiliser les identifiants d’authentification dans le sandbox](/fr/products/sandboxes/operations/object-storage-access#step-5-use-the-credentials-inside-the-sandbox).

Pour restreindre l’identifiant d’authentification à un préfixe de clé, utilisez `object_prefix`. Pour les charges de travail qui ne font que lire des données, utilisez `ObjectStoragePermission.READ`.

Pour les données temporaires volumineuses qui restent locales au sandbox, joignez plutôt un volume. Voir [Volumes](/fr/products/sandboxes/volumes).