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

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)

Les lignes sont découpées en utilisant des sauts de ligne universels. Les séquences suivantes sont reconnues comme marques de fin de ligne : la convention de fin de ligne Unix '\n', la convention Windows '\r\n', ainsi que l’ancienne convention Macintosh '\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. En plus des méthodes de 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.

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

Conjointement, MemoryFileUploadHandler et 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.

É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³¹ 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¹⁰ 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.

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