L’objet File

Le module django.core.files et ses sous-modules contiennent les classes intégrées pour la gestion de base des fichiers dans Django.

La classe File

class File(file_object, name=None)[source]

La classe File est une enveloppe légère autour d’un objet fichier de Python, doté de quelques ajouts spécifiques à Django. En interne, Django utilise cette classe lorsqu’il a besoin de représenter un fichier.

Les objets File possèdent les attributs et méthodes suivants :

name

Le nom du fichier, comprenant le chemin relatif du réglage MEDIA_ROOT.

size

La taille du fichier en octets.

file

L’objet fichier que cette classe enveloppe.

Soyez prudent avec cet attribut dans les sous-classes.

Certaines sous-classes de File, incluant ContentFile et FieldFile, peuvent remplacer cet attribut par un objet autre qu’un objet fichier Python. Dans ces cas, cet attribut peut être lui-même une sous-classe de File (et par nécessairement la même sous-classe). Autant que possible, utilisez les attributs et méthodes de la sous-classe elle-même plutôt que ceux de l’attribut file des sous-classes.

mode

Le mode lecture/écriture du fichier.

open(mode=None, *args, **kwargs)[source]

Ouvre ou réouvre le fichier (et réinitialise son pointeur par File.seek(0)). Le paramètre mode autorise les mêmes valeurs que la fonction intégrée de Python open(). *args et **kwargs sont transmis après mode à la fonction intégrée open() de Python.

Lors de la réouverture d’un fichier, mode écrase le mode avec lequel le fichier a été initialement ouvert ; None signifie que le mode initial doit être utilisé pour la réouverture.

Vous pouvez l’utiliser comme un gestionnaire de contexte, par ex. with file.open() as f:.

Changed in Django 5.0:

La prise en charge de la transmission de *args et **kwargs a été ajoutée.

__iter__()[source]

Lit le fichier par itération en renvoyant les lignes une à une.

chunks(chunk_size=None)[source]

Lit le fichier par itération en renvoyant des blocs (« chunks »)de la taille indiquée. La valeur par défaut de chunk_size est 64 Ko.

C’est particulièrement utile pour les gros fichiers car cela permet de les lire en flux à partir du disque en évitant de stocker la totalité du fichier en mémoire.

multiple_chunks(chunk_size=None)[source]

Renvoie True si la taille du fichier nécessite de le partitionner en plusieurs blocs pour le lire en entier, en fonction de la taille chunk_size.

close()[source]

Ferme le fichier.

En plus des méthodes mentionnées, File expose les attributs et méthodes suivants de son objet file: encoding, fileno, flush, isatty, newlines, read, readinto, readline, readlines, seek, tell, truncate, write, writelines, readable(), writable() et seekable().

La classe ContentFile

class ContentFile(content, name=None)[source]

La classe ContentFile hérite de File, mais contrairement à celle-ci, elle n’agit que sur du contenu de type chaîne (octets aussi admis), plutôt que sur un vrai fichier. Par exemple :

from django.core.files.base import ContentFile

f1 = ContentFile("esta frase está en español")
f2 = ContentFile(b"these are bytes")

La classe ImageFile

class ImageFile(file_object, name=None)[source]

Django fournit une classe intégrée tout exprès pour les images. django.core.files.images.ImageFile hérite de tous les attributs et méthodes de File, et offre en plus les éléments suivants :

width

Largeur de l’image en pixels.

height

Hauteur de l’image en pixels.

Méthodes supplémentaires pour les fichiers liés à des objets

Tout fichier File associé à un objet (comme pour Car.photo ci-dessous) possède également quelque méthodes supplémentaires :

File.save(name, content, save=True)

Enregistre un nouveau fichier avec le nom de fichier et le contenu indiqués. Cela ne remplacera pas le fichier existant, mais un nouveau fichier sera créé et l’objet sera mis à jour pour pointer vers ce fichier. Si save vaut True, la méthode save() du modèle sera appelée après l’enregistrement du fichier. C’est-à-dire que ces deux lignes :

>>> car.photo.save("myphoto.jpg", content, save=False)
>>> car.save()

sont équivalentes à :

>>> car.photo.save("myphoto.jpg", content, save=True)

Notez que le paramètre content doit être soit une instance de File , soit une sous-classe de File, comme par exemple ContentFile.

File.delete(save=True)

Enlève le fichier de l’instance de modèle et supprime le fichier concerné. Si save vaut True, la méthode save() du modèle sera appelée après la suppression du fichier.