diff options
Diffstat (limited to 'parts/django/docs/howto/custom-file-storage.txt')
| -rw-r--r-- | parts/django/docs/howto/custom-file-storage.txt | 90 |
1 files changed, 0 insertions, 90 deletions
diff --git a/parts/django/docs/howto/custom-file-storage.txt b/parts/django/docs/howto/custom-file-storage.txt deleted file mode 100644 index 1b0f32f..0000000 --- a/parts/django/docs/howto/custom-file-storage.txt +++ /dev/null @@ -1,90 +0,0 @@ -Writing a custom storage system -=============================== - -.. currentmodule:: django.core.files.storage - -If you need to provide custom file storage -- a common example is storing files -on some remote system -- you can do so by defining a custom storage class. -You'll need to follow these steps: - -#. Your custom storage system must be a subclass of - ``django.core.files.storage.Storage``:: - - from django.core.files.storage import Storage - - class MyStorage(Storage): - ... - -#. Django must be able to instantiate your storage system without any arguments. - This means that any settings should be taken from ``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 - ... - -#. Your storage class must implement the ``_open()`` and ``_save()`` methods, - along with any other methods appropriate to your storage class. See below for - more on these methods. - - In addition, if your class provides local file storage, it must override - the ``path()`` method. - -Your custom storage system may override any of the storage methods explained in -:doc:`/ref/files/storage`, but you **must** implement the following methods: - - * :meth:`Storage.delete` - * :meth:`Storage.exists` - * :meth:`Storage.listdir` - * :meth:`Storage.size` - * :meth:`Storage.url` - -You'll also usually want to use hooks specifically designed for custom storage -objects. These are: - -``_open(name, mode='rb')`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Required**. - -Called by ``Storage.open()``, this is the actual mechanism the storage class -uses to open the file. This must return a ``File`` object, though in most cases, -you'll want to return some subclass here that implements logic specific to the -backend storage system. - -``_save(name, content)`` -~~~~~~~~~~~~~~~~~~~~~~~~ - -Called by ``Storage.save()``. The ``name`` will already have gone through -``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a -``File`` object itself. - -Should return the actual name of name of the file saved (usually the ``name`` -passed in, but if the storage needs to change the file name return the new name -instead). - -``get_valid_name(name)`` ------------------------- - -Returns a filename suitable for use with the underlying storage system. The -``name`` argument passed to this method is the original filename sent to the -server, after having any path information removed. Override this to customize -how non-standard characters are converted to safe filenames. - -The code provided on ``Storage`` retains only alpha-numeric characters, periods -and underscores from the original filename, removing everything else. - -``get_available_name(name)`` ----------------------------- - -Returns a filename that is available in the storage mechanism, possibly taking -the provided filename into account. The ``name`` argument passed to this method -will have already cleaned to a filename valid for the storage system, according -to the ``get_valid_name()`` method described above. - -The code provided on ``Storage`` simply appends ``"_1"``, ``"_2"``, etc. to the -filename until it finds one that's available in the destination directory. |