# Documentation Django 6.0.7

# API de stockage des fichiers

## Obtention de la classe de stockage par défaut

Django offre des manières pratiques d’accéder à la classe de stockage par défaut :

storages

  Un objet de type dictionnaire qui permet de récupérer une instance de stockage en utilisant son alias défini dans `STORAGES`.

  `storages` possède un attribut `backends`, qui contient par défaut la valeur brute indiquée dans `STORAGES`.

  De plus, `storages` fournit une méthode `create_storage()` qui accepte le dictionnaire utilisé dans `STORAGES` pour un moteur, et renvoie une instance de stockage basée sur cette définition de moteur. Cela peut être utile pour des paquets de tierce partie ayant besoin d’instancier des stockages dans les tests :

      >>> from django.core.files.storage import storages
      >>> storages.backends
      {'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'},
       'staticfiles': {'BACKEND': 'django.contrib.staticfiles.storage.StaticFilesStorage'},
       'custom': {'BACKEND': 'package.storage.CustomStorage'}}
      >>> storage_instance = storages.create_storage({"BACKEND": "package.storage.CustomStorage"})

class DefaultStorage

  `DefaultStorage` offre un accès différé au système de stockage par défaut tel que défini par la clé `default` dans `STORAGES`. `DefaultStorage` utilise `storages` en interne.

default_storage

  `default_storage` est une instance de `DefaultStorage`.

## La classe `FileSystemStorage`

class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None, allow_overwrite=False)

  La classe `FileSystemStorage` implémente le stockage de fichiers de base sur un système de fichiers local. Elle hérite de `Storage` et offre des implémentations pour toutes les méthodes publiques de celle-ci.

  Note

  La méthode `FileSystemStorage.delete()` ne renvoie pas d’exception si le nom de fichier fourni en paramètre n’existe pas.

  location

    Chemin absolu vers le répertoire qui contiendra les fichiers. La valeur par défaut est la valeur du réglage `MEDIA_ROOT`.

  base_url

    URL de base pour servir les fichiers stockés à cet emplacement. La valeur par défaut est la valeur du réglage `MEDIA_URL`.

  file_permissions_mode

    Les permissions de système de fichiers que le fichier reçoit quand il est enregistré. La valeur par défaut correspond à `FILE_UPLOAD_PERMISSIONS`.

  directory_permissions_mode

    Les permissions de système de fichiers que le répertoire reçoit quand il est enregistré. La valeur par défaut correspond à `FILE_UPLOAD_DIRECTORY_PERMISSIONS`.

  allow_overwrite

    Drapeau pour contrôler la permission d’enregistrement de nouveaux fichiers en écrasant des fichiers existants. Contient `False` par défaut.

  get_created_time(name)

    Renvoie une heure `datetime` de la valeur ctime du système, c’est-à-dire `os.path.getctime()`. Sur certains systèmes (comme Unix), il s’agit de la date de la dernière modification de métadonnée du fichier alors que sur d’autres systèmes (comme Windows), il s’agit de la date de création du fichier.

## La classe `InMemoryStorage`

class InMemoryStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

  La classe `InMemoryStorage` implémente un stockage de fichiers en mémoire vive. Il n’a aucune persistence mais peut être utile pour accélérer les tests en évitant d’accéder au disque.

  location

    Chemin absolu vers le nom ue répertoire dédié aux fichiers. La valeur par défaut est la valeur du réglage `MEDIA_ROOT`.

  base_url

    URL de base pour servir les fichiers stockés à cet emplacement. La valeur par défaut est la valeur du réglage `MEDIA_URL`.

  file_permissions_mode

    Les permissions de système de fichiers attribuées aux fichiers, données par compatibilité avec `FileSystemStorage`. La valeur par défaut correspond à `FILE_UPLOAD_PERMISSIONS`.

  directory_permissions_mode

    Les permissions de système de fichiers attribuées aux répertoires, données par compatibilité avec `FileSystemStorage`. La valeur par défaut correspond à `FILE_UPLOAD_DIRECTORY_PERMISSIONS`.

## La classe `Storage`

class Storage

  La classe `Storage` fournit une API standardisée pour le stockage de fichiers, accompagnée d’un ensemble de comportements par défaut que tous les autres systèmes de stockage peuvent hériter ou surcharger en cas de besoin.

  Note

  Lorsque les méthodes renvoient des objets `datetime` naïfs, le fuseau horaire réellement utilisé correspond à la valeur actuelle de `os.environ['TZ']`. Notez que cette valeur est généralement définie à partir du réglage `TIME_ZONE` de Django.

  delete(name)

    Supprime le fichier désigné par `name`. Si la suppression n’est pas prise en charge par le système de stockage cible, une exception `NotImplementedError` est générée.

  exists(name)

    Renvoie `True` si le fichier désigné par le nom indiqué existe déjà dans le système de stockage.

  get_accessed_time(name)

    Renvoie une date/heure `datetime` du dernier accès au fichier. Pour les systèmes de stockage incapables de renvoyer la date du dernier accès, cette méthode génère l’exception `NotImplementedError`.

    Si `USE_TZ` vaut `True`, renvoie un objet `datetime` conscient, sinon un objet `datetime` naïf est renvoyé dans le fuseau horaire local.

  get_alternative_name(file_root, file_ext)

    Renvoie un nom de fichier différent basé sur les paramètres `file_root` et `file_ext`. 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 sur la base du paramètre `name` et qui est disponible pour recevoir un nouveau contenu à écrire sur le système de stockage cible.

    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à, `get_alternative_name()` est appelée pour obtenir un nom différent.

  get_created_time(name)

    Renvoie une date/heure `datetime` de création du fichier. Pour les systèmes de stockage incapables de renvoyer la date de création, cette méthode génère l’exception `NotImplementedError`.

    Si `USE_TZ` vaut `True`, renvoie un objet `datetime` conscient, sinon un objet `datetime` naïf est renvoyé dans le fuseau horaire local.

  get_modified_time(name)

    Renvoie une date/heure `datetime` de la dernière modification du fichier. Pour les systèmes de stockage incapables de renvoyer la date de dernière modification, cette méthode génère l’exception `NotImplementedError`.

    Si `USE_TZ` vaut `True`, renvoie un objet `datetime` conscient, sinon un objet `datetime` naïf est renvoyé dans le fuseau horaire local.

  get_valid_name(name)

    Renvoie un nom de fichier sur la base du paramètre `name` et qui est adapté aux usages du système de stockage cible.

  generate_filename(filename)

    Valide le nom de fichier `filename` en appelant `get_valid_name` et renvoie un nom de fichier à transmettre à la méthode `save()`.

    Le paramètre `filename` peut inclure un chemin tel que renvoyé par `FileField.upload_to`. Dans ce cas, le chemin ne sera pas transmis à `get_valid_name`, mais sera ajouté au début du nom résultant.

    L’implémentation par défaut utilise des opérations `os.path`. Surchargez cette méthode si ce n’est pas approprié pour votre type de stockage.

  listdir(path)

    Énumère le contenu du chemin indiqué, renvoyant un tuple de deux listes ; la première est une liste de répertoires, la seconde contient les fichiers. Pour les systèmes de stockage qui ne peuvent pas fournir une telle liste, une exception `NotImplementedError` est générée.

  open(name, mode='rb')

    Ouvre le fichier désigné par `name`. Notez que bien que le fichier renvoyé soit garanti être un objet `File`, il se peut qu’il s’agisse d’une sous-classe. Dans le cas de systèmes de stockage distants, cela signifie que la lecture et l’écriture peuvent être lentes, il faut le savoir.

  path(name)

    Le chemin du système de fichiers local où le fichier peut être ouvert en utilisant l’appel Python standard `open()`. Pour les systèmes de stockage qui ne sont pas accessibles à partir du système de fichiers local, cette méthode génère une exception `NotImplementedError`.

  save(name, content, max_length=None)

    Enregistre un nouveau fichier en utilisant le système de stockage, de préférence avec le nom indiqué. Si le nom `name` est déjà utilisé pour un autre fichier, le système de stockage peut modifier le nom de fichier afin d’obtenir un nom unique si nécessaire. Le nom réellement utilisé pour stocker le fichier est renvoyé.

    Le paramètre `max_length` est transmis plus loin à `get_available_name()`.

    Le paramètre `content` doit être une instance de `django.core.files.File` ou d’un objet de type fichier pouvant être enveloppé par `File`.

  size(name)

    Renvoie la taille totale en octets du fichier désigné par `name`. Pour les systèmes de stockage qui ne peuvent pas renvoyer la taille des fichiers, cette méthode génère l’exception `NotImplementedError`.

  url(name)

    Renvoie l’URL permettant d’accéder au contenu du fichier désigné par `name`. Pour les systèmes de stockage qui ne permettent pas l’accès par URL, cette méthode génère l’exception `NotImplementedError`.

Il existe également des solutions maintenues par la communauté !

Django possède un écosystème dynamique. Il existe des moteurs de stockage mis en évidence sur la page Community Ecosystem. La grille Storage Backends de Django Packages présente encore d’autres options à votre disposition.