Ce document décrit l’API Django d’accès aux fichiers adaptée par exemple aux fichiers envoyés par les utilisateurs. Les API de plus bas niveau sont assez générales pour pouvoir être utilisées dans d’autres buts. Si vous souhaitez gérer les « fichiers statiques » (JS, CSS, etc.), consultez Gestion des fichiers statiques (par ex. images, JavaScript, CSS).
\nPar défaut, Django stocke les fichiers localement, en fonction des réglages MEDIA_ROOT et MEDIA_URL. Les exemples ci-dessous partent du principe que vous utilisez ces valeurs par défaut.
Cependant, Django permet d’écrire des systèmes de stockage de fichiers spécialisés permettant de personnaliser complètement l’endroit et la façon dont Django stocke les fichiers. La deuxième partie de ce document décrit le fonctionnement des ces systèmes de stockage.
\nQuand vous utilisez un FileField ou un ImageField, Django fournit un ensemble d’API pour pouvoir manipuler le fichier correspondant.
Considérez le modèle suivant qui utilise un ImageField pour stocker une photo :
from django.db import models\n\n\nclass Car(models.Model):\n name = models.CharField(max_length=255)\n price = models.DecimalField(max_digits=5, decimal_places=2)\n photo = models.ImageField(upload_to="cars")\n specs = models.FileField(upload_to="specs")\nToute instance de Car possède un attribut photo qu’il est possible d’utiliser pour obtenir les détails de la photo jointe :
>>> car = Car.objects.get(name="57 Chevy")\n>>> car.photo\n<ImageFieldFile: cars/chevy.jpg>\n>>> car.photo.name\n'cars/chevy.jpg'\n>>> car.photo.path\n'/media/cars/chevy.jpg'\n>>> car.photo.url\n'https://media.example.com/cars/chevy.jpg'\nCet objet (car.photo dans l’exemple) est un objet File, ce qui signifie qu’il possède toutes les méthodes et les attributs documentés ci-dessous.
Par exemple, vous pouvez modifier le nom de fichier en définissant l’attribut name du fichier à un chemin relatif à l’emplacement de stockage des fichiers (MEDIA_ROOT si vous utilisez le FileSystemStorage par défaut) :
>>> import os\n>>> from django.conf import settings\n>>> initial_path = car.photo.path\n>>> car.photo.name = "cars/chevy_ii.jpg"\n>>> new_path = os.path.join(settings.MEDIA_ROOT, car.photo.name)\n>>> # Move the file on the filesystem\n>>> os.rename(initial_path, new_path)\n>>> car.save()\n>>> car.photo.path\n'/media/cars/chevy_ii.jpg'\n>>> car.photo.path == new_path\nTrue\nPour enregistrer un fichier existant sur le disque dans un champ FileField:
>>> from pathlib import Path\n>>> from django.core.files import File\n>>> path = Path("/some/external/specs.pdf")\n>>> car = Car.objects.get(name="57 Chevy")\n>>> with path.open(mode="rb") as f:\n... car.specs = File(f, name=path.name)\n... car.save()\n...\nEn interne, Django utilise une instance de django.core.files.File chaque fois qu’il a besoin de représenter un fichier.
La plupart du temps, vous utiliserez l’objet File que Django vous transmet (par exemple un fichier joint à un modèle comme ci-dessus ou peut-être un fichier téléversé).
Si vous avez besoin de construire vous-même un objet File, la façon la plus simple est de le créer en utilisant un objet file de Python :
>>> from django.core.files import File\n\n# Create a Python file object using open()\n>>> f = open("/path/to/hello.world", "w")\n>>> myfile = File(f)\nIl est maintenant possible d’utiliser les attributs et les méthodes documentés de la classe File.
Il faut savoir que les fichiers créés de cette façon ne sont pas fermés automatiquement. L’approche suivante peut être employée pour fermer automatiquement les fichiers :
\n>>> from django.core.files import File\n\n# Create a Python file object using open() and the with statement\n>>> with open("/path/to/hello.world", "w") as f:\n... myfile = File(f)\n... myfile.write("Hello World")\n...\n>>> myfile.closed\nTrue\n>>> f.closed\nTrue\nLa fermeture des fichiers est particulièrement importante lors de l’accès en boucle à des champs fichier pour un grand nombre d’objets. Si les fichiers ne sont pas fermés manuellement après les avoir lus, il y a un risque d’épuisement des descripteurs de fichiers. Cela peut amener à l’erreur suivante :
\nOSError: [Errno 24] Too many open files\nEn arrière-plan, Django délègue les décisions au sujet des emplacements des fichiers et de la manière de les stocker à un système de stockage de fichiers. C’est cet objet qui s’occupe réellement des systèmes de fichiers, de l’ouverture et de la lecture des fichiers, etc.
\nLe stockage de fichiers par défaut de Django est 'django.core.files.storage.FileSystemStorage'. Si vous n’indiquez pas explicitement un système de stockage dans la clé default du réglage STORAGES, c’est celui qui sera utilisé.
Lisez ci-dessous pour obtenir des détails sur le système de stockage de fichiers intégré par défaut et lisez Écriture d’une classe de stockage personnalisée pour plus d’informations sur l’écriture de son propre système de stockage de fichiers.
\nBien que la plupart du temps il soit plus opportun de manipuler un objet File (qui délègue au stockage adapté pour ce fichier), il est possible d’utiliser directement un stockage de fichiers. Vous pouvez créer une instance d’une classe de stockage de fichiers personnalisé ou, plus souvent utile, vous pouvez utiliser le système de stockage global par défaut :
>>> from django.core.files.base import ContentFile\n>>> from django.core.files.storage import default_storage\n\n>>> path = default_storage.save("path/to/file", ContentFile(b"new content"))\n>>> path\n'path/to/file'\n\n>>> default_storage.size(path)\n11\n>>> default_storage.open(path).read()\nb'new content'\n\n>>> default_storage.delete(path)\n>>> default_storage.exists(path)\nFalse\nVoir API de stockage des fichiers concernant l’API de stockage de fichiers.
\nDjango fournit une classe django.core.files.storage.FileSystemStorage qui implémente les éléments de base du stockage de fichiers sur un système de fichiers.
Par exemple, le code suivant stocke les fichiers téléversés dans /media/photos quelle que soit la valeur du réglage MEDIA_ROOT:
from django.core.files.storage import FileSystemStorage\nfrom django.db import models\n\nfs = FileSystemStorage(location="/media/photos")\n\n\nclass Car(models.Model):\n ...\n photo = models.ImageField(storage=fs)\nLes systèmes de stockage personnalisés fonctionnent de la même manière : vous pouvez les transmettre comme paramètre storage d’un champ FileField.
Vous pouvez transmettre un objet exécutable comme paramètre storage de FileField ou de ImageField. Cela permet de modifier le stockage utilisé au moment de l’exécution, choisissant par exemple différents stockages en fonction de l’environnement.
Your callable will be evaluated when your model classes are loaded, and must\nreturn an instance of Storage.
Par exemple :
\nfrom django.conf import settings\nfrom django.db import models\nfrom .storages import MyLocalStorage, MyRemoteStorage\n\n\ndef select_storage():\n return MyLocalStorage() if settings.DEBUG else MyRemoteStorage()\n\n\nclass MyModel(models.Model):\n my_file = models.FileField(storage=select_storage)\nAfin de définir un stockage défini dans le réglage STORAGES, vous pouvez utiliser storages:
from django.core.files.storage import storages\n\n\ndef select_storage():\n return storages["mystorage"]\n\n\nclass MyModel(models.Model):\n upload = models.FileField(storage=select_storage)\nBecause the callable is evaluated when your model classes are loaded, if you\nneed to override the STORAGES setting in tests, you should use a\nLazyObject subclass instead:
from django.core.files.storage import storages\nfrom django.utils.functional import LazyObject\n\n\nclass OtherStorage(LazyObject):\n def _setup(self):\n self._wrapped = storages["mystorage"]\n\n\nmy_storage = OtherStorage()\n\n\nclass MyModel(models.Model):\n upload = models.FileField(storage=my_storage)\nL’objet LazyObject diffère l’évaluation du stockage jusqu’au moment où il est réellement employé, ce qui permet à override_settings() de faire effet :
@override_settings(\n STORAGES={\n "mystorage": {\n "BACKEND": "django.core.files.storage.InMemoryStorage",\n }\n }\n)\ndef test_storage():\n model = MyModel()\n assert isinstance(model.upload.storage, InMemoryStorage)\n