Debian Codegraph @

docs/howto/custom-file-storage.txt

raw
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"]