1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
================
File storage API
================
.. module:: django.core.files.storage
Getting the default storage class
=================================
Django provides convenient ways to access the default storage class:
.. data:: storages
A dictionary-like object that allows retrieving a storage instance using
its alias as defined by :setting:`STORAGES`.
``storages`` has an attribute ``backends``, which defaults to the raw value
provided in :setting:`STORAGES`.
Additionally, ``storages`` provides a ``create_storage()`` method that
accepts the dictionary used in :setting:`STORAGES` for a backend, and
returns a storage instance based on that backend definition. This may be
useful for third-party packages needing to instantiate storages in tests:
.. code-block:: pycon
>>> from django.core.files.storage import storages
>>> storages.backends
{'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'},
'staticfiles': {'BACKEND': 'django.contrib.staticfiles.storage.StaticFilesStorage'},
'custom': {'BACKEND': 'package.storage.CustomStorage'}}
>>> storage_instance = storages.create_storage({"BACKEND": "package.storage.CustomStorage"})
.. class:: DefaultStorage
:class:`~django.core.files.storage.DefaultStorage` provides
lazy access to the default storage system as defined by ``default`` key in
:setting:`STORAGES`. :class:`DefaultStorage` uses
:data:`~django.core.files.storage.storages` internally.
.. data:: default_storage
:data:`~django.core.files.storage.default_storage` is an instance of the
:class:`~django.core.files.storage.DefaultStorage`.
The ``FileSystemStorage`` class
===============================
.. class:: FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None, allow_overwrite=False)
The :class:`~django.core.files.storage.FileSystemStorage` class implements
basic file storage on a local filesystem. It inherits from
:class:`~django.core.files.storage.Storage` and provides implementations
for all the public methods thereof.
.. note::
The ``FileSystemStorage.delete()`` method will not raise an exception
if the given file name does not exist.
.. attribute:: location
Absolute path to the directory that will hold the files.
Defaults to the value of your :setting:`MEDIA_ROOT` setting.
.. attribute:: base_url
URL that serves the files stored at this location.
Defaults to the value of your :setting:`MEDIA_URL` setting.
.. attribute:: file_permissions_mode
The file system permissions that the file will receive when it is
saved. Defaults to :setting:`FILE_UPLOAD_PERMISSIONS`.
.. attribute:: directory_permissions_mode
The file system permissions that the directory will receive when it is
saved. Defaults to :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS`.
.. attribute:: allow_overwrite
.. versionadded:: 5.1
Flag to control allowing saving a new file over an existing one.
Defaults to ``False``.
.. method:: get_created_time(name)
Returns a :class:`~datetime.datetime` of the system's ctime, i.e.
:func:`os.path.getctime`. On some systems (like Unix), this is the
time of the last metadata change, and on others (like Windows), it's
the creation time of the file.
The ``InMemoryStorage`` class
=============================
.. class:: InMemoryStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)
The :class:`~django.core.files.storage.InMemoryStorage` class implements
a memory-based file storage. It has no persistence, but can be useful for
speeding up tests by avoiding disk access.
.. attribute:: location
Absolute path to the directory name assigned to files. Defaults to the
value of your :setting:`MEDIA_ROOT` setting.
.. attribute:: base_url
URL that serves the files stored at this location.
Defaults to the value of your :setting:`MEDIA_URL` setting.
.. attribute:: file_permissions_mode
The file system permissions assigned to files, provided for
compatibility with ``FileSystemStorage``. Defaults to
:setting:`FILE_UPLOAD_PERMISSIONS`.
.. attribute:: directory_permissions_mode
The file system permissions assigned to directories, provided for
compatibility with ``FileSystemStorage``. Defaults to
:setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS`.
The ``Storage`` class
=====================
.. class:: Storage
The :class:`~django.core.files.storage.Storage` class provides a
standardized API for storing files, along with a set of default
behaviors that all other storage systems can inherit or override
as necessary.
.. note::
When methods return naive ``datetime`` objects, the effective timezone
used will be the current value of ``os.environ['TZ']``; note that this
is usually set from Django's :setting:`TIME_ZONE`.
.. method:: delete(name)
Deletes the file referenced by ``name``. If deletion is not supported
on the target storage system this will raise ``NotImplementedError``
instead.
.. method:: exists(name)
Returns ``True`` if a file referenced by the given name already exists
in the storage system.
.. method:: get_accessed_time(name)
Returns a :class:`~datetime.datetime` of the last accessed time of the
file. For storage systems unable to return the last accessed time this
will raise :exc:`NotImplementedError`.
If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
otherwise returns a naive ``datetime`` in the local timezone.
.. method:: get_alternative_name(file_root, file_ext)
Returns an alternative filename based on the ``file_root`` and
``file_ext`` parameters, an underscore plus a random 7 character
alphanumeric string is appended to the filename before the extension.
.. method:: get_available_name(name, max_length=None)
Returns a filename based on the ``name`` parameter that's free and
available for new content to be written to on the target storage
system.
The length of the filename will not exceed ``max_length``, if provided.
If a free unique filename cannot be found, a
:exc:`SuspiciousFileOperation
<django.core.exceptions.SuspiciousOperation>` exception will be raised.
If a file with ``name`` already exists, :meth:`get_alternative_name` is
called to obtain an alternative name.
.. method:: get_created_time(name)
Returns a :class:`~datetime.datetime` of the creation time of the file.
For storage systems unable to return the creation time this will raise
:exc:`NotImplementedError`.
If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
otherwise returns a naive ``datetime`` in the local timezone.
.. method:: get_modified_time(name)
Returns a :class:`~datetime.datetime` of the last modified time of the
file. For storage systems unable to return the last modified time this
will raise :exc:`NotImplementedError`.
If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
otherwise returns a naive ``datetime`` in the local timezone.
.. method:: get_valid_name(name)
Returns a filename based on the ``name`` parameter that's suitable
for use on the target storage system.
.. method:: generate_filename(filename)
Validates the ``filename`` by calling :attr:`get_valid_name()` and
returns a filename to be passed to the :meth:`save` method.
The ``filename`` argument may include a path as returned by
:attr:`FileField.upload_to <django.db.models.FileField.upload_to>`.
In that case, the path won't be passed to :attr:`get_valid_name()` but
will be prepended back to the resulting name.
The default implementation uses :mod:`os.path` operations. Override
this method if that's not appropriate for your storage.
.. method:: listdir(path)
Lists the contents of the specified path, returning a 2-tuple of lists;
the first item being directories, the second item being files. For
storage systems that aren't able to provide such a listing, this will
raise a ``NotImplementedError`` instead.
.. method:: open(name, mode='rb')
Opens the file given by ``name``. Note that although the returned file
is guaranteed to be a ``File`` object, it might actually be some
subclass. In the case of remote file storage this means that
reading/writing could be quite slow, so be warned.
.. method:: path(name)
The local filesystem path where the file can be opened using Python's
standard ``open()``. For storage systems that aren't accessible from
the local filesystem, this will raise ``NotImplementedError`` instead.
.. method:: save(name, content, max_length=None)
Saves a new file using the storage system, preferably with the name
specified. If there already exists a file with this name ``name``, the
storage system may modify the filename as necessary to get a unique
name. The actual name of the stored file will be returned.
The ``max_length`` argument is passed along to
:meth:`get_available_name`.
The ``content`` argument must be an instance of
:class:`django.core.files.File` or a file-like object that can be
wrapped in ``File``.
.. method:: size(name)
Returns the total size, in bytes, of the file referenced by ``name``.
For storage systems that aren't able to return the file size this will
raise ``NotImplementedError`` instead.
.. method:: url(name)
Returns the URL where the contents of the file referenced by ``name``
can be accessed. For storage systems that don't support access by URL
this will raise ``NotImplementedError`` instead.
|
