|
1 File storage API |
|
2 ================ |
|
3 |
|
4 .. module:: django.core.files.storage |
|
5 |
|
6 Getting the current storage class |
|
7 --------------------------------- |
|
8 |
|
9 Django provides two convenient ways to access the current storage class: |
|
10 |
|
11 .. class:: DefaultStorage |
|
12 |
|
13 :class:`~django.core.files.storage.DefaultStorage` provides |
|
14 lazy access to the current default storage system as defined by |
|
15 :setting:`DEFAULT_FILE_STORAGE`. :class:`DefaultStorage` uses |
|
16 :func:`~django.core.files.storage.get_storage_class` internally. |
|
17 |
|
18 .. function:: get_storage_class([import_path=None]) |
|
19 |
|
20 Returns a class or module which implements the storage API. |
|
21 |
|
22 When called without the ``import_path`` parameter ``get_storage_class`` |
|
23 will return the current default storage system as defined by |
|
24 :setting:`DEFAULT_FILE_STORAGE`. If ``import_path`` is provided, |
|
25 ``get_storage_class`` will attempt to import the class or module from the |
|
26 given path and will return it if successful. An exception will be |
|
27 raised if the import is unsuccessful. |
|
28 |
|
29 The FileSystemStorage Class |
|
30 --------------------------- |
|
31 |
|
32 .. class:: FileSystemStorage |
|
33 |
|
34 The :class:`~django.core.files.storage.FileSystemStorage` class implements |
|
35 basic file storage on a local filesystem. It inherits from |
|
36 :class:`~django.core.files.storage.Storage` and provides implementations |
|
37 for all the public methods thereof. |
|
38 |
|
39 .. note:: |
|
40 |
|
41 The :class:`FileSystemStorage.delete` method will not raise |
|
42 raise an exception if the given file name does not exist. |
|
43 |
|
44 The Storage Class |
|
45 ----------------- |
|
46 |
|
47 .. class:: Storage |
|
48 |
|
49 The :class:`~django.core.files.storage.Storage` class provides a |
|
50 standardized API for storing files, along with a set of default |
|
51 behaviors that all other storage systems can inherit or override |
|
52 as necessary. |
|
53 |
|
54 .. method:: delete(name) |
|
55 |
|
56 Deletes the file referenced by ``name``. If deletion is not supported |
|
57 on the targest storage system this will raise ``NotImplementedError`` |
|
58 instead |
|
59 |
|
60 .. method:: exists(name) |
|
61 |
|
62 Returns ``True`` if a file referened by the given name already exists |
|
63 in the storage system, or ``False`` if the name is available for a new |
|
64 file. |
|
65 |
|
66 .. method:: get_available_name(name) |
|
67 |
|
68 Returns a filename based on the ``name`` parameter that's free and |
|
69 available for new content to be written to on the target storage |
|
70 system. |
|
71 |
|
72 |
|
73 .. method:: get_valid_name(name) |
|
74 |
|
75 Returns a filename based on the ``name`` parameter that's suitable |
|
76 for use on the target storage system. |
|
77 |
|
78 .. method:: listdir(path) |
|
79 |
|
80 Lists the contents of the specified path, returning a 2-tuple of lists; |
|
81 the first item being directories, the second item being files. For |
|
82 storage systems that aren't able to provide such a listing, this will |
|
83 raise a ``NotImplementedError`` instead. |
|
84 |
|
85 .. method:: open(name, mode='rb') |
|
86 |
|
87 Opens the file given by ``name``. Note that although the returned file |
|
88 is guaranteed to be a ``File`` object, it might actually be some |
|
89 subclass. In the case of remote file storage this means that |
|
90 reading/writing could be quite slow, so be warned. |
|
91 |
|
92 .. method:: path(name) |
|
93 |
|
94 The local filesystem path where the file can be opened using Python's |
|
95 standard ``open()``. For storage systems that aren't accessible from |
|
96 the local filesystem, this will raise ``NotImplementedError`` instead. |
|
97 |
|
98 .. method:: save(name, content) |
|
99 |
|
100 Saves a new file using the storage system, preferably with the name |
|
101 specified. If there already exists a file with this name ``name``, the |
|
102 storage system may modify the filename as necessary to get a unique |
|
103 name. The actual name of the stored file will be returned. |
|
104 |
|
105 The ``content`` argument must be an instance of |
|
106 :class:`django.core.files.File` or of a subclass of |
|
107 :class:`~django.core.files.File`. |
|
108 |
|
109 .. method:: size(name) |
|
110 |
|
111 Returns the total size, in bytes, of the file referenced by ``name``. |
|
112 For storage systems that aren't able to return the file size this will |
|
113 raise ``NotImplementedError`` instead. |
|
114 |
|
115 .. method:: url(name) |
|
116 |
|
117 Returns the URL where the contents of the file referenced by ``name`` |
|
118 can be accessed. For storage systems that don't support access by URL |
|
119 this will raise ``NotImplementedError`` instead. |