| 1 |
=================================== |
| 2 |
How to write a custom storage class |
| 3 |
=================================== |
| 4 |
|
| 5 |
.. currentmodule:: django.core.files.storage |
| 6 |
|
| 7 |
If you need to provide custom file storage -- a common example is storing files |
| 8 |
on some remote system -- you can do so by defining a custom storage class. |
| 9 |
You'll need to follow these steps: |
| 10 |
|
| 11 |
#. Your custom storage system must be a subclass of |
| 12 |
``django.core.files.storage.Storage``:: |
| 13 |
|
| 14 |
from django.core.files.storage import Storage |
| 15 |
|
| 16 |
|
| 17 |
class MyStorage(Storage): ... |
| 18 |
|
| 19 |
#. Django must be able to instantiate your storage system without any arguments. |
| 20 |
This means that any settings should be taken from ``django.conf.settings``:: |
| 21 |
|
| 22 |
from django.conf import settings |
| 23 |
from django.core.files.storage import Storage |
| 24 |
|
| 25 |
|
| 26 |
class MyStorage(Storage): |
| 27 |
def __init__(self, option=None): |
| 28 |
if not option: |
| 29 |
option = settings.CUSTOM_STORAGE_OPTIONS |
| 30 |
... |
| 31 |
|
| 32 |
#. Your storage class must implement the :meth:`_open()` and :meth:`_save()` |
| 33 |
methods, along with any other methods appropriate to your storage class. See |
| 34 |
below for more on these methods. |
| 35 |
|
| 36 |
In addition, if your class provides local file storage, it must override |
| 37 |
the ``path()`` method. |
| 38 |
|
| 39 |
#. Your storage class must be :ref:`deconstructible <custom-deconstruct-method>` |
| 40 |
so it can be serialized when it's used on a field in a migration. As long |
| 41 |
as your field has arguments that are themselves |
| 42 |
:ref:`serializable <migration-serializing>`, you can use the |
| 43 |
``django.utils.deconstruct.deconstructible`` class decorator for this |
| 44 |
(that's what Django uses on FileSystemStorage). |
| 45 |
|
| 46 |
By default, the following methods raise ``NotImplementedError`` and will |
| 47 |
typically have to be overridden: |
| 48 |
|
| 49 |
* :meth:`Storage.delete` |
| 50 |
* :meth:`Storage.exists` |
| 51 |
* :meth:`Storage.listdir` |
| 52 |
* :meth:`Storage.size` |
| 53 |
* :meth:`Storage.url` |
| 54 |
|
| 55 |
Note however that not all these methods are required and may be deliberately |
| 56 |
omitted. As it happens, it is possible to leave each method unimplemented and |
| 57 |
still have a working Storage. |
| 58 |
|
| 59 |
By way of example, if listing the contents of certain storage backends turns |
| 60 |
out to be expensive, you might decide not to implement ``Storage.listdir()``. |
| 61 |
|
| 62 |
Another example would be a backend that only handles writing to files. In this |
| 63 |
case, you would not need to implement any of the above methods. |
| 64 |
|
| 65 |
Ultimately, which of these methods are implemented is up to you. Leaving some |
| 66 |
methods unimplemented will result in a partial (possibly broken) interface. |
| 67 |
|
| 68 |
You'll also usually want to use hooks specifically designed for custom storage |
| 69 |
objects. These are: |
| 70 |
|
| 71 |
.. method:: _open(name, mode='rb') |
| 72 |
|
| 73 |
**Required**. |
| 74 |
|
| 75 |
Called by ``Storage.open()``, this is the actual mechanism the storage class |
| 76 |
uses to open the file. This must return a ``File`` object, though in most cases, |
| 77 |
you'll want to return some subclass here that implements logic specific to the |
| 78 |
backend storage system. The :exc:`FileNotFoundError` exception should be raised |
| 79 |
when a file doesn't exist. |
| 80 |
|
| 81 |
.. method:: _save(name, content) |
| 82 |
|
| 83 |
Called by ``Storage.save()``. The ``name`` will already have gone through |
| 84 |
``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a |
| 85 |
``File`` object itself. |
| 86 |
|
| 87 |
Should return the actual name of the file saved (usually the ``name`` passed |
| 88 |
in, but if the storage needs to change the file name return the new name |
| 89 |
instead). |
| 90 |
|
| 91 |
.. method:: get_valid_name(name) |
| 92 |
|
| 93 |
Returns a filename suitable for use with the underlying storage system. The |
| 94 |
``name`` argument passed to this method is either the original filename sent to |
| 95 |
the server or, if ``upload_to`` is a callable, the filename returned by that |
| 96 |
method after any path information is removed. Override this to customize how |
| 97 |
non-standard characters are converted to safe filenames. |
| 98 |
|
| 99 |
The code provided on ``Storage`` retains only alpha-numeric characters, periods |
| 100 |
and underscores from the original filename, removing everything else. |
| 101 |
|
| 102 |
.. method:: get_alternative_name(file_root, file_ext) |
| 103 |
|
| 104 |
Returns an alternative filename based on the ``file_root`` and ``file_ext`` |
| 105 |
parameters. By default, an underscore plus a random 7 character alphanumeric |
| 106 |
string is appended to the filename before the extension. |
| 107 |
|
| 108 |
.. method:: get_available_name(name, max_length=None) |
| 109 |
|
| 110 |
Returns a filename that is available in the storage mechanism, possibly taking |
| 111 |
the provided filename into account. The ``name`` argument passed to this method |
| 112 |
will have already cleaned to a filename valid for the storage system, according |
| 113 |
to the ``get_valid_name()`` method described above. |
| 114 |
|
| 115 |
The length of the filename will not exceed ``max_length``, if provided. If a |
| 116 |
free unique filename cannot be found, a :exc:`SuspiciousFileOperation |
| 117 |
<django.core.exceptions.SuspiciousOperation>` exception is raised. |
| 118 |
|
| 119 |
If a file with ``name`` already exists, ``get_alternative_name()`` is called to |
| 120 |
obtain an alternative name. |
| 121 |
|
| 122 |
.. _using-custom-storage-engine: |
| 123 |
|
| 124 |
Use your custom storage engine |
| 125 |
============================== |
| 126 |
|
| 127 |
The first step to using your custom storage with Django is to tell Django about |
| 128 |
the file storage backend you'll be using. This is done using the |
| 129 |
:setting:`STORAGES` setting. This setting maps storage aliases, which are a way |
| 130 |
to refer to a specific storage throughout Django, to a dictionary of settings |
| 131 |
for that specific storage backend. The settings in the inner dictionaries are |
| 132 |
described fully in the :setting:`STORAGES` documentation. |
| 133 |
|
| 134 |
Storages are then accessed by alias from the |
| 135 |
:data:`django.core.files.storage.storages` dictionary:: |
| 136 |
|
| 137 |
from django.core.files.storage import storages |
| 138 |
|
| 139 |
example_storage = storages["example"] |