|
1 Writing a custom storage system |
|
2 =============================== |
|
3 |
|
4 .. currentmodule:: django.core.files.storage |
|
5 |
|
6 If you need to provide custom file storage -- a common example is storing files |
|
7 on some remote system -- you can do so by defining a custom storage class. |
|
8 You'll need to follow these steps: |
|
9 |
|
10 #. Your custom storage system must be a subclass of |
|
11 ``django.core.files.storage.Storage``:: |
|
12 |
|
13 from django.core.files.storage import Storage |
|
14 |
|
15 class MyStorage(Storage): |
|
16 ... |
|
17 |
|
18 #. Django must be able to instantiate your storage system without any arguments. |
|
19 This means that any settings should be taken from ``django.conf.settings``:: |
|
20 |
|
21 from django.conf import settings |
|
22 from django.core.files.storage import Storage |
|
23 |
|
24 class MyStorage(Storage): |
|
25 def __init__(self, option=None): |
|
26 if not option: |
|
27 option = settings.CUSTOM_STORAGE_OPTIONS |
|
28 ... |
|
29 |
|
30 #. Your storage class must implement the ``_open()`` and ``_save()`` methods, |
|
31 along with any other methods appropriate to your storage class. See below for |
|
32 more on these methods. |
|
33 |
|
34 In addition, if your class provides local file storage, it must override |
|
35 the ``path()`` method. |
|
36 |
|
37 Your custom storage system may override any of the storage methods explained in |
|
38 :doc:`/ref/files/storage`, but you **must** implement the following methods: |
|
39 |
|
40 * :meth:`Storage.delete` |
|
41 * :meth:`Storage.exists` |
|
42 * :meth:`Storage.listdir` |
|
43 * :meth:`Storage.size` |
|
44 * :meth:`Storage.url` |
|
45 |
|
46 You'll also usually want to use hooks specifically designed for custom storage |
|
47 objects. These are: |
|
48 |
|
49 ``_open(name, mode='rb')`` |
|
50 ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
51 |
|
52 **Required**. |
|
53 |
|
54 Called by ``Storage.open()``, this is the actual mechanism the storage class |
|
55 uses to open the file. This must return a ``File`` object, though in most cases, |
|
56 you'll want to return some subclass here that implements logic specific to the |
|
57 backend storage system. |
|
58 |
|
59 ``_save(name, content)`` |
|
60 ~~~~~~~~~~~~~~~~~~~~~~~~ |
|
61 |
|
62 Called by ``Storage.save()``. The ``name`` will already have gone through |
|
63 ``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a |
|
64 ``File`` object itself. |
|
65 |
|
66 Should return the actual name of name of the file saved (usually the ``name`` |
|
67 passed in, but if the storage needs to change the file name return the new name |
|
68 instead). |
|
69 |
|
70 ``get_valid_name(name)`` |
|
71 ------------------------ |
|
72 |
|
73 Returns a filename suitable for use with the underlying storage system. The |
|
74 ``name`` argument passed to this method is the original filename sent to the |
|
75 server, after having any path information removed. Override this to customize |
|
76 how non-standard characters are converted to safe filenames. |
|
77 |
|
78 The code provided on ``Storage`` retains only alpha-numeric characters, periods |
|
79 and underscores from the original filename, removing everything else. |
|
80 |
|
81 ``get_available_name(name)`` |
|
82 ---------------------------- |
|
83 |
|
84 Returns a filename that is available in the storage mechanism, possibly taking |
|
85 the provided filename into account. The ``name`` argument passed to this method |
|
86 will have already cleaned to a filename valid for the storage system, according |
|
87 to the ``get_valid_name()`` method described above. |
|
88 |
|
89 The code provided on ``Storage`` simply appends ``"_1"``, ``"_2"``, etc. to the |
|
90 filename until it finds one that's available in the destination directory. |