← Back to branch summary

~ubuntu-branches/ubuntu/jaunty/python-django/jaunty

« back to all changes in this revision

Viewing changes to docs/howto/custom-file-storage.txt

  • Committer: Bazaar Package Importer
  • Author(s): Scott James Remnant, Eddy Mulyono
  • Date: 2008-09-16 12:18:47 UTC
  • mfrom: (1.1.5 upstream) (4.1.1 lenny)
  • Revision ID: james.westby@ubuntu.com-20080916121847-mg225rg5mnsdqzr0
Tags: 1.0-1ubuntu1
https://launchpad.net/bugs/264191
* Merge from Debian (LP: #264191), remaining changes:
  - Run test suite on build.

[Eddy Mulyono]
* Update patch to workaround network test case failures.

Show diffs side-by-side

added added

removed removed

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