--- title: "Écriture d’une classe de stockage personnalisée" version: 4.2 locale: fr source: https://docs.djangoproject.com/fr/4.2/howto/custom-file-storage/ canonical: https://djangodocs.dev/fr/4.2/howto/custom-file-storage/ --- # Écriture d’une classe de stockage personnalisée 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 : 1. 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): ... ``` 2. 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 ... ``` 3. Votre classe de stockage doit implémenter les méthodes [`_open()`](#django.core.files.storage._open) et [`_save()`](#django.core.files.storage._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()`. 4. Votre classe de stockage doit être [déconstructible](/fr/4.2/topics/migrations/#custom-deconstruct-method) 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](/fr/4.2/topics/migrations/#migration-serializing), vous pouvez utiliser le décorateur de classe `django.utils.deconstruct.deconstructible` pour cela (c’est ce que Django utilise pour `FileSystemStorage`). Par défaut, les méthodes suivantes génèrent `NotImplementedError` et doivent typiquement être surchargées : - [`Storage.delete()`](/fr/4.2/ref/files/storage/#django.core.files.storage.Storage.delete) - [`Storage.exists()`](/fr/4.2/ref/files/storage/#django.core.files.storage.Storage.exists) - [`Storage.listdir()`](/fr/4.2/ref/files/storage/#django.core.files.storage.Storage.listdir) - [`Storage.size()`](/fr/4.2/ref/files/storage/#django.core.files.storage.Storage.size) - [`Storage.url()`](/fr/4.2/ref/files/storage/#django.core.files.storage.Storage.url) 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. C’est l’exception [`FileNotFoundError`](https://docs.python.org/3/library/exceptions.html#FileNotFoundError) qui doit être générée lorsqu’un fichier n’existe pas. #### `_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_alternative_name(file_root, file_ext)` Renvoie un nom de fichier différent basé sur les paramètres `file_root` et `file_ext`. Par défaut, un soulignement suivi d’une chaîne aléatoire de 7 caractères alphanumériques sont ajoutés à la fin du nom du fichier avant l’extension. #### `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`](/fr/4.2/ref/exceptions/#django.core.exceptions.SuspiciousOperation) est générée. Si un fichier avec `name` existe déjà, `get_alternative_name()` est appelée pour obtenir un nom différent. ## Utiliser son propre moteur de stockage personnalisé > **New in Django 4.2** La première chose à faire lorsqu’on veut utiliser son propre stockage avec Django est de le renseigner au sujet du moteur de stockage que vous souhaitez utiliser. Cela se fait au niveau du réglage [`STORAGES`](/fr/4.2/ref/settings/#std-setting-STORAGES). Ce réglage fait correspondre des alias de stockage, qui sont une manière de se référer à des stockages spécifiques dans le code de Django, à un dictionnaire de réglages pour le moteur de stockage concerné. Les réglages du dictionnaire interne sont détaillés dans la documentation de [`STORAGES`](/fr/4.2/ref/settings/#std-setting-STORAGES). On peut ensuite accéder aux stockages par leur alias à partir du dictionnaire data:django.core.files.storage.storages: ``` from django.core.files.storage import storages example_storage = storages["example"] ```