---
title: "Fichiers téléversés et gestionnaires de téléversement"
version: 6.1
locale: fr
source: https://docs.djangoproject.com/fr/6.1/ref/files/uploads/
canonical: https://djangodocs.dev/fr/6.1/ref/files/uploads/
---
# Fichiers téléversés et gestionnaires de téléversement

## Fichiers téléversés

#### `class UploadedFile`

Durant les téléversements de fichiers, les données de fichiers réelles sont stockées dans [`request.FILES`](/fr/6.1/ref/request-response/#django.http.HttpRequest.FILES). Chaque élément de ce dictionnaire est un objet `UploadedFile` (ou une sous-classe), un adaptateur autour d’un fichier téléversé. En général, c’est par l’une de ces méthodes que l’on accède au contenu téléversé :

#### `UploadedFile.read()`

Lit toutes les données du fichier téléversé. Soyez prudent avec cette méthode : si le fichier concerné est très gros, il pourrait dépasser les capacités de votre système si vous essayez de le lire en mémoire. Il est plutôt recommandé d’utiliser `chunks()`, voir ci-dessous.

#### `UploadedFile.multiple_chunks(chunk_size=None)`

Renvoie `True` si le fichier téléversé est assez gros pour avoir besoin d’être lu en plusieurs segments. Par défaut, cela concerne tous les fichiers plus gros que 2,5 mébioctets, mais cela peut être configuré ; voir ci-dessous.

#### `UploadedFile.chunks(chunk_size=None)`

Un générateur renvoyant des segments du fichier. Si `multiple_chunks()` vaut `True`, il est conseillé d’utiliser cette méthode avec une boucle au lieu d’utiliser `read()`.

En pratique, il est souvent plus simple de toujours utiliser `chunks()`. En bouclant sur `chunks()` au lieu d’appeler `read()`, on peut s’assurer que les gros fichiers ne saturent pas la mémoire du système.

Voici quelques attributs utiles de `UploadedFile`:

#### `UploadedFile.name`

Le nom du fichier téléversé (par ex. `mon_fichier.txt`).

#### `UploadedFile.size`

La taille en octets du fichier téléversé.

#### `UploadedFile.content_type`

L’en-tête `content-type` associé au fichier téléversé (par ex.  `text/plain` ou `application/pdf`). Comme toute donnée en provenance d’un utilisateur, on ne peut pas être certain que le fichier soit vraiment de ce type. Il est toujours nécessaire de valider que le contenu du fichier corresponde bien au type de contenu prétendu par l’en-tête, «  avoir confiance mais contrôler ».

#### `UploadedFile.content_type_extra`

Un dictionnaire contenant des paramètres supplémentaires transmis à l’en-tête `content-type`. Ils sont généralement fournis par des services comme Google App Engine qui interceptent et gèrent les téléversements de fichiers à votre place. Par conséquent, votre gestionnaire peut ne pas recevoir le contenu du fichier téléversé, mais plutôt une URL ou un autre pointeur vers le fichier (voir [**RFC 2388**](https://datatracker.ietf.org/doc/html/rfc2388.html#section-5.3)).

#### `UploadedFile.charset`

Pour les types de contenu `text/*`, le codage de caractères (par ex. `utf8`) indiqué par le navigateur. Encore une fois, « avoir confiance, mais contrôler » est la stratégie la plus sage ici.

> **Note**
>
> Comme pour les fichiers Python normaux, vous pouvez lire le fichier ligne par ligne en bouclant sur le fichier téléversé :
>
> ```
> for line in uploadedfile:
>     do_something_with(line)
> ```
>
> Lines are split using [universal newlines](https://docs.python.org/3/glossary.html#term-universal-newlines). The following are
> recognized as ending a line: the Unix end-of-line convention `'\n'`, the
> Windows convention `'\r\n'`, and the old Macintosh convention `'\r'`.

Parmi les sous-classes de `UploadedFile`, on trouve :

#### `class TemporaryUploadedFile`

Un fichier téléversé vers un emplacement temporaire (c.-à-d. en flux vers disque). Cette classe est utilisée par [`TemporaryFileUploadHandler`](#django.core.files.uploadhandler.TemporaryFileUploadHandler). En plus des méthodes de [`UploadedFile`](#django.core.files.uploadedfile.UploadedFile), elle possède une méthode supplémentaire :

#### `TemporaryUploadedFile.temporary_file_path()`

Renvoie le chemin complet du fichier téléversé temporaire.

#### `class InMemoryUploadedFile`

Un fichier téléversé en mémoire (c.-à-d. en flux vers mémoire). Cette classe est utilisée par [`MemoryFileUploadHandler`](#django.core.files.uploadhandler.MemoryFileUploadHandler).

## Gestionnaires de téléversement intégrés

Conjointement, [`MemoryFileUploadHandler`](#django.core.files.uploadhandler.MemoryFileUploadHandler) et [`TemporaryFileUploadHandler`](#django.core.files.uploadhandler.TemporaryFileUploadHandler) définissent le comportement Django par défaut de téléversement de fichier en plaçant les petits fichiers en mémoire et les plus gros sur le disque. Ils se trouvent dans `django.core.files.uploadhandler`.

#### `class MemoryFileUploadHandler`

Gestionnaire de téléversement de fichier pour transférer en flux les téléversements vers la mémoire (utilisé pour de petits fichiers).

#### `class TemporaryFileUploadHandler`

Gestionnaire de téléversement qui écrit en flux les données vers un fichier temporaire en utilisant [`TemporaryUploadedFile`](#django.core.files.uploadedfile.TemporaryUploadedFile).

## Écriture de gestionnaires de téléversement personnalisés

#### `class FileUploadHandler`

Tous les gestionnaires de téléversement de fichiers doivent hériter de `django.core.files.uploadhandler.FileUploadHandler`. Ils peuvent être placés à n’importe quel endroit.

### Méthodes obligatoires

Les gestionnaires de téléversement personnalisés **doivent** définir les méthodes suivantes :

#### `FileUploadHandler.receive_data_chunk(raw_data, start)`

Reçoit un « segment » de données du fichier téléversé.

`raw_data` est une chaîne d’octets contenant les données envoyées.

`start` est la position dans le fichier correspondant au début de ce segment `raw_data`.

Les données que vous renvoyez seront retransmises aux méthodes `receive_data_chunk` des gestionnaires de téléversement suivants. De cette façon, un gestionnaire peut être un « filtre » pour d’autres gestionnaires.

Renvoyez `None` depuis `receive_data_chunk` pour empêcher les gestionnaires de téléversement restants de recevoir ce segment. Cela peut être utile si vous stockez vous-même les données reçues et que vous ne souhaitez pas que les gestionnaires suivants stockent une copie des données.

Si vous générez une exception `StopUpload` ou `SkipFile`, le téléversement s’interrompt ou le fichier est complètement ignoré.

#### `FileUploadHandler.file_complete(file_size)`

Appelée lorsque le téléversement d’un fichier est terminé.

Le gestionnaire doit renvoyer un objet `UploadedFile` qui sera stocké dans `request.FILES`. Les gestionnaires peuvent aussi renvoyer `None` pour indiquer que l’objet `UploadedFile` doit provenir d’un des gestionnaires de téléversement suivants.

### Méthodes facultatives

Les gestionnaires de téléversement peuvent aussi définir l’une des méthodes ou des attributs facultatifs suivants :

#### `FileUploadHandler.chunk_size`

Taille, en octets, des segments que Django stocke en mémoire et transmet au gestionnaire. En clair, cet attribut contrôle la taille des segments qui sont envoyés à `FileUploadHandler.receive_data_chunk`.

Pour des performances optimales, la taille des segments devrait être divisible par `4` sans excéder 2 Gio (2<sup>31</sup> octets). Lorsque différentes tailles de segment sont indiquées par différents gestionnaires, Django utilise la taille de segment la plus petite d’entre elles.

La valeur par défaut est 64\*2<sup>10</sup> octets ou 64 Kio.

#### `FileUploadHandler.new_file(field_name, file_name, content_type, content_length, charset, content_type_extra)`

Fonction de rappel signalant qu’un nouvel envoi de fichier démarre. Elle est appelée avant que les données commencent à être envoyées à un gestionnaire de téléversement.

`field_name` est le nom (chaîne) du champ de fichier `<input>`.

`file_name` est le nom de fichier indiqué par le navigateur.

`content_type` est le type MIME indiqué par le navigateur, par exemple `'image/jpeg'`.

`content_length` est la taille de l’image indiquée par le navigateur. Il arrive que cette valeur ne soit pas indiquée et contienne `None`.

`charset` est le jeu de caractères (par ex. `utf8`) indiqué par le navigateur. Comme `content_length`, il arrive que cette valeur ne soit pas donnée.

`content_type_extra` contient des informations supplémentaires au sujet du fichier selon l’en-tête `content-type`. Voir [`UploadedFile.content_type_extra`](#django.core.files.uploadedfile.UploadedFile.content_type_extra).

Cette méthode peut générer une exception `StopFutureHandlers` pour empêcher d’autres gestionnaires de gérer ce fichier après celui-ci.

#### `FileUploadHandler.upload_complete()`

Fonction de rappel signalant que tout le téléversement est terminé (tous les fichiers).

#### `FileUploadHandler.upload_interrupted()`

Fonction de rappel signalant que le téléversement a été interrompu, par ex. lorsque l’utilisateur a fermé son navigateur avant que le téléversement soit terminé.

#### `FileUploadHandler.handle_raw_input(input_data, META, content_length, boundary, encoding)`

Permet au gestionnaire de surcharger complètement l’analyse de l’entrée HTTP brute.

`input_data` est un objet de type fichier prenant en charge la lecture (`read()`).

`META` est le même objet que `request.META`.

`content_length` est la taille des données dans `input_data`. Ne lisez pas plus de `content_length` octets à partir de `input_data`.

`boundary` est la frontière MIME de cette requête.

`encoding` est le codage de cette requête.

Renvoyez `None` si vous voulez que la gestion du téléversement se poursuive, ou un tuple `(POST, FILES)` si vous voulez renvoyer directement les nouvelles structures de données prêtes à l’emploi par la requête.