PageRenderTime 122ms CodeModel.GetById 60ms app.highlight 1ms RepoModel.GetById 59ms app.codeStats 0ms

/docs/howto/custom-file-storage.txt

https://code.google.com/p/mango-py/
Plain Text | 90 lines | 65 code | 25 blank | 0 comment | 0 complexity | 4b50ab217ce0d01559bdaec25a082003 MD5 | raw file
 1Writing a custom storage system
 2===============================
 3
 4.. currentmodule:: django.core.files.storage
 5
 6If you need to provide custom file storage -- a common example is storing files
 7on some remote system -- you can do so by defining a custom storage class.
 8You'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
37Your 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
46You'll also usually want to use hooks specifically designed for custom storage
47objects. These are:
48
49``_open(name, mode='rb')``
50~~~~~~~~~~~~~~~~~~~~~~~~~~
51
52**Required**.
53
54Called by ``Storage.open()``, this is the actual mechanism the storage class
55uses to open the file. This must return a ``File`` object, though in most cases,
56you'll want to return some subclass here that implements logic specific to the
57backend storage system.
58
59``_save(name, content)``
60~~~~~~~~~~~~~~~~~~~~~~~~
61
62Called 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
66Should return the actual name of name of the file saved (usually the ``name``
67passed in, but if the storage needs to change the file name return the new name
68instead).
69
70``get_valid_name(name)``
71~~~~~~~~~~~~~~~~~~~~~~~~
72
73Returns 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
75server, after having any path information removed. Override this to customize
76how non-standard characters are converted to safe filenames.
77
78The code provided on ``Storage`` retains only alpha-numeric characters, periods
79and underscores from the original filename, removing everything else.
80
81``get_available_name(name)``
82~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
84Returns a filename that is available in the storage mechanism, possibly taking
85the provided filename into account. The ``name`` argument passed to this method
86will have already cleaned to a filename valid for the storage system, according
87to the ``get_valid_name()`` method described above.
88
89The code provided on ``Storage`` simply appends ``"_1"``, ``"_2"``, etc. to the
90filename until it finds one that's available in the destination directory.