API de stockage des fichiers

Accès à la classe de stockage en cours

Django offre deux manières pratiques d’accéder à la classe de stockage active :

class DefaultStorage

DefaultStorage offre un accès différé au système de stockage par défaut en cours tel que défini par DEFAULT_FILE_STORAGE. DefaultStorage utilise get_storage_class() en interne.

get_storage_class(import_path=None)

Renvoie une classe ou un module qui implémente l’API de stockage.

Lorsqu’on l’appelle sans le paramètre import_path, get_storage_class renvoie le système de stockage par défaut en cours tel que défini par DEFAULT_FILE_STORAGE. Si import_path est fourni, get_storage_class essaie d’importer la classe ou le module désigné par le chemin donné et le renvoie en cas de succès. Une exception est générée si l’importation échoue.

La classe FileSystemStorage

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

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.

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.

Note

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

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.

Changed in Django 3.1:

La prise en charge des chemins de type pathlib.Path a été ajoutée à la méthode FileSystemStorage.save().

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)

Deletes the file referenced by name. If deletion is not supported on the target storage system this will raise NotImplementedError instead.

exists(name)

Renvoie True si le fichier désigné par le nom indiqué existe déjà dans le système de stockage, ou False si le nom est disponible pour un nouveau fichier.

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)

New in Django 3.0.

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.