Создание пользовательской системы хранения

Если вам необходимо предоставить пользовательское хранилище файлов — распространённым примером является хранение файлов на какой-либо удалённой системе — вы можете сделать это, определив пользовательский класс хранилища. Вам необходимо выполнить следующие шаги:

1. Ваша пользовательская система хранения должна быть подклассом django.core.files.storage.Storage.

   from django.core.files.storage import Storage
   
   class MyStorage(Storage):
       ...
   

2. Django должен иметь возможность инициализировать вашу систему хранения без аргументов. Это означает, что все настройки должны быть взяты из 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. Ваш класс хранилища должен реализовывать методы _open() и _save(), а также любые другие методы, подходящие для вашего класса хранилища. Более подробная информация об этих методах приведена ниже.

   Кроме того, если ваш класс предоставляет локальное хранилище файлов, он должен переопределять метод path().

4. Ваш класс хранилища должен быть деконструируемым, чтобы его можно было сериализовать при использовании в поле в миграции. Пока ваше поле имеет аргументы, которые сами являются сериализуемыми, вы можете использовать декоратор класса django.utils.deconstruct.deconstructible для этого (так Django использует FileSystemStorage).

По умолчанию следующие методы вызывают NotImplementedError и обычно должны быть переопределены:

• Storage.delete()
• Storage.exists()
• Storage.listdir()
• Storage.size()
• Storage.url()

Однако не все эти методы являются обязательными и могут быть намеренно опушены. В некоторых случаях можно оставить каждый метод нереализованным и при этом сохранить работоспособность хранилища.

Например, если перечисление содержимого определённых хранилищ оказывается дорогостоящим, вы можете решить не реализовывать Storage.listdir().

Другим примером является бэкенд, который обрабатывает только запись в файлы. В этом случае вам не нужно реализовывать ни один из вышеперечисленных методов.

В конечном счёте, какие из этих методов будут реализованы, зависит от вас. Оставление некоторых методов нереализованными приведёт к частичному (возможно, неработоспособному) интерфейсу.

Вы также обычно захотите использовать хуки, специально предназначенные для пользовательских объектов хранилища. Это:

_open(name, mode='rb')

Обязательно.

Вызывается Storage.open(), это фактический механизм, который использует класс хранилища для открытия файла. Он должен возвращать объект File, хотя в большинстве случаев вы захотите вернуть какой-либо подкласс, который реализует логику, специфичную для бэкенд-системы хранения.

_save(name, content)

Вызывается Storage.save(). name уже пройдёт через get_valid_name() и get_available_name(), а content будет являться объектом File.

Должен возвращать фактическое имя сохранённого файла (обычно имя name , переданное в качестве аргумента, но если хранилищу нужно изменить имя файла, необходимо вернуть новое имя).

get_valid_name(name)

Возвращает имя файла, подходящее для использования с основой системой хранения. Аргумент name , переданный в этот метод, — это либо исходное имя файла, отправленное на сервер, либо, если upload_to является вызываемым объектом, имя файла, возвращённое этим методом после удаления любой информации о пути. Переопределите этот метод, чтобы настроить, как нестандартные символы преобразуются в безопасные имена файлов.

В приведённом на Storage коде сохраняются только буквенно-цифровые символы, точки и символы подчёркивания из исходного имени файла, удаляя всё остальное.

get_alternative_name(file_root, file_ext)

Возвращает альтернативное имя файла, основываясь на параметрах file_root и file_ext. По умолчанию к имени файла перед расширением добавляется символ подчёркивания и случайная 7-символьная буквенно-цифровая строка.

get_available_name(name, max_length=None)

Возвращает имя файла, доступное в механизме хранения, возможно, учитывая предоставленное имя файла. Аргумент name , переданный в этот метод, уже очищен до имени файла, допустимого для системы хранения, в соответствии с методом get_valid_name() , описанным выше.

Длина имени файла не будет превышать max_length, если она указана. Если уникальное свободное имя файла не может быть найдено, генерируется исключение SuspiciousFileOperation.

Если файл с именем name уже существует, вызывается get_alternative_name() для получения альтернативного имени.