Écriture d’un système de stockage personnalisé¶
Si vous avez besoin de fournir un stockage de fichiers personnalisé, typiquement pour stocker des fichiers dans un système distant, vous pouvez le faire en définissant une classe de stockage personnalisée. Il faudra suivre ces étapes :
Votre système de stockage personnalisé doit être une sous-classe de
django.core.files.storage.Storage
:from django.core.files.storage import Storage class MyStorage(Storage): ...
Django doit être capable d’instancier votre système de stockage sans paramètre. Cela signifie que tout réglage doit provenir de
django.conf.settings
:from django.conf import settings from django.core.files.storage import Storage class MyStorage(Storage): def __init__(self, option=None): if not option: option = settings.CUSTOM_STORAGE_OPTIONS ...
Votre classe de stockage doit implémenter les méthodes
_open()
et_save()
, en plus de toute autre méthode adéquate pour votre classe de stockage. Voir ci-dessous pour plus de détails sur ces méthodes.De plus, si votre classe propose du stockage de fichiers locaux, elle doit surcharger la méthode
path()
.Votre classe de stockage doit être déconstructible pour pouvoir être sérialisée lorsqu’elle est référencée dans un champ dans une migration. Tant que les paramètres du champ sont eux-mêmes sérialisables, vous pouvez utiliser le décorateur de classe
django.utils.deconstruct.deconstructible
pour cela (c’est ce que Django utilise pourFileSystemStorage
).
Par défaut, les méthodes suivantes génèrent NotImplementedError
et doivent typiquement être surchargées :
Notez cependant que ces méthodes ne sont pas toutes obligatoires et peuvent être délibérément omises. Il est même possible d’obtenir une classe de stockage fonctionnelle sans implémenter aucune de ces méthodes.
À titre d’exemple, si l’énumération du contenu de certains moteurs de stockage se révèle coûteuse, il est tout à fait possible de décider de ne pas implémenter Storage.listdir
.
Un autre exemple pourrait être un moteur qui ne gère que l’écriture dans des fichiers. Dans ce cas, il ne serait pas nécessaire d’implémenter une seule des méthodes ci-dessus.
Au final, le choix des méthodes à implémenter vous revient. En laissant certaines méthodes non implémentées, l’interface proposée sera partielle (voire défectueuse).
Il est généralement souhaitable d’implémenter les méthodes tout spécialement conçues pour les objets de stockage personnalisé. Ce sont :
-
_open
(name, mode='rb')¶
Obligatoire.
Appelée par Storage.open()
, c’est le mécanisme utilisé par la classe de stockage pour ouvrir un fichier. Elle doit renvoyer un objet File
, même si dans la plupart des cas, elle renverra plutôt une sous-classe qui implémente la logique particulière du moteur de stockage.
-
_save
(name, content)¶
Appelée par Storage.save()
. Le paramètre name
aura déjà passé par get_valid_name()
et get_available_name()
, et content
sera un objet de type File
.
Elle doit renvoyer le nom réel du fichier enregistré (normalement le paramètre name
, mais si le stockage a besoin de modifier le nom de fichier, c’est le nouveau nom qui devra être renvoyé).
-
get_valid_name
(name)¶
Renvoie un nom de fichier acceptable par le système de stockage sous-jacent. Le paramètre name
passé à cette méthode est soit le nom de fichier original envoyé au serveur, soit, si upload_to
est exécutable, le nom de fichier renvoyé par cette méthode dépourvu de toute notion de chemin. Surchargez cette méthode pour personnaliser la manière dont des caractères non standards sont convertis pour former des noms de fichiers sûrs.
Le code fourni par Storage
ne conserve que les caractères alphanumériques, les points et les soulignements du nom de fichier original, supprimant tout le reste.
-
get_available_name
(name, max_length=None)¶
Renvoie un nom de fichier disponible (non existant) dans le mécanisme de stockage, prenant potentiellement en compte le nom de fichier fourni. Le paramètre name
transmis à cette méthode aura déjà été nettoyé afin d’être un nom de fichier valable pour le système de stockage, en accord avec la méthode get_valid_name()
décrite ci-dessus.
La longueur du nom de fichier ne dépassera pas max_length
, si cette option est indiquée. Si un nom de fichier unique n’est pas disponible, une exception SuspiciousFileOperation
est générée.
Si un fichier avec name
existe déjà, un soulignement suivi d’une chaîne aléatoire de 7 caractères alphanumériques est ajouté à la fin du nom du fichier avant l’extension.