mirror of
https://github.com/django/django.git
synced 2025-10-28 16:16:12 +00:00
c6c25adf6d
Fixes #8358, #8396, #8724, #9043, #9128, #9247, #9267, #9267, #9375, #9409, #9414, #9416, #9446, #9454, #9464, #9503, #9518, #9533, #9657, #9658, #9683, #9733, #9771, #9835, #9836, #9837, #9897, #9906, #9912, #9945, #9986, #9992, #10055, #10084, #10091, #10145, #10245, #10257, #10309, #10358, #10359, #10424, #10426, #10508, #10531, #10551, #10635, #10637, #10656, #10658, #10690, #10699, #19528. Thanks to all the respective authors of those tickets. git-svn-id: http://code.djangoproject.com/svn/django/trunk@10371 bcc190cf-cafb-0310-a4f2-bffc1f526a37
93 lines
3.3 KiB
Plaintext
93 lines
3.3 KiB
Plaintext
.. _howto-custom-file-storage:
|
|
|
|
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
|
|
:ref:`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 underscores to the filename
|
|
until it finds one that's available in the destination directory.
|