Debian Codegraph @

docs/topics/files.txt

raw
1 ==============
2 Managing files
3 ==============
4
5 This document describes Django's file access APIs for files such as those
6 uploaded by a user. The lower level APIs are general enough that you could use
7 them for other purposes. If you want to handle "static files" (JS, CSS, etc.),
8 see :doc:`/howto/static-files/index`.
9
10 By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
11 :setting:`MEDIA_URL` settings. The examples below assume that you're using these
12 defaults.
13
14 However, Django provides ways to write custom `file storage systems`_ that
15 allow you to completely customize where and how Django stores files. The
16 second half of this document describes how these storage systems work.
17
18 .. _file storage systems: `File storage`_
19
20 Using files in models
21 =====================
22
23 When you use a :class:`~django.db.models.FileField` or
24 :class:`~django.db.models.ImageField`, Django provides a set of APIs you can use
25 to deal with that file.
26
27 Consider the following model, using an :class:`~django.db.models.ImageField` to
28 store a photo::
29
30 from django.db import models
31
32
33 class Car(models.Model):
34 name = models.CharField(max_length=255)
35 price = models.DecimalField(max_digits=5, decimal_places=2)
36 photo = models.ImageField(upload_to="cars")
37 specs = models.FileField(upload_to="specs")
38
39 Any ``Car`` instance will have a ``photo`` attribute that you can use to get at
40 the details of the attached photo:
41
42 .. code-block:: pycon
43
44 >>> car = Car.objects.get(name="57 Chevy")
45 >>> car.photo
46 <ImageFieldFile: cars/chevy.jpg>
47 >>> car.photo.name
48 'cars/chevy.jpg'
49 >>> car.photo.path
50 '/media/cars/chevy.jpg'
51 >>> car.photo.url
52 'https://media.example.com/cars/chevy.jpg'
53
54 This object -- ``car.photo`` in the example -- is a ``File`` object, which means
55 it has all the methods and attributes described below.
56
57 .. note::
58 The file is saved as part of saving the model in the database, so the actual
59 file name used on disk cannot be relied on until after the model has been
60 saved.
61
62 For example, you can change the file name by setting the file's
63 :attr:`~django.core.files.File.name` to a path relative to the file storage's
64 location (:setting:`MEDIA_ROOT` if you are using the default
65 :class:`~django.core.files.storage.FileSystemStorage`):
66
67 .. code-block:: pycon
68
69 >>> import os
70 >>> from django.conf import settings
71 >>> initial_path = car.photo.path
72 >>> car.photo.name = "cars/chevy_ii.jpg"
73 >>> new_path = os.path.join(settings.MEDIA_ROOT, car.photo.name)
74 >>> # Move the file on the filesystem
75 >>> os.rename(initial_path, new_path)
76 >>> car.save()
77 >>> car.photo.path
78 '/media/cars/chevy_ii.jpg'
79 >>> car.photo.path == new_path
80 True
81
82 To save an existing file on disk to a :class:`~django.db.models.FileField`:
83
84 .. code-block:: pycon
85
86 >>> from pathlib import Path
87 >>> from django.core.files import File
88 >>> path = Path("/some/external/specs.pdf")
89 >>> car = Car.objects.get(name="57 Chevy")
90 >>> with path.open(mode="rb") as f:
91 ... car.specs = File(f, name=path.name)
92 ... car.save()
93 ...
94
95 .. note::
96
97 While :class:`~django.db.models.ImageField` non-image data attributes, such
98 as ``height``, ``width``, and ``size`` are available on the instance, the
99 underlying image data cannot be used without reopening the image. For
100 example:
101
102 .. code-block:: pycon
103
104 >>> from PIL import Image
105 >>> car = Car.objects.get(name="57 Chevy")
106 >>> car.photo.width
107 191
108 >>> car.photo.height
109 287
110 >>> image = Image.open(car.photo)
111 # Raises ValueError: seek of closed file.
112 >>> car.photo.open()
113 <ImageFieldFile: cars/chevy.jpg>
114 >>> image = Image.open(car.photo)
115 >>> image
116 <PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=191x287 at 0x7F99A94E9048>
117
118 The ``File`` object
119 ===================
120
121 Internally, Django uses a :class:`django.core.files.File` instance any time it
122 needs to represent a file.
123
124 Most of the time you'll use a ``File`` that Django's given you (i.e. a file
125 attached to a model as above, or perhaps an uploaded file).
126
127 If you need to construct a ``File`` yourself, the easiest way is to create one
128 using a Python built-in ``file`` object:
129
130 .. code-block:: pycon
131
132 >>> from django.core.files import File
133
134 # Create a Python file object using open()
135 >>> f = open("/path/to/hello.world", "w")
136 >>> myfile = File(f)
137
138 Now you can use any of the documented attributes and methods
139 of the :class:`~django.core.files.File` class.
140
141 Be aware that files created in this way are not automatically closed.
142 The following approach may be used to close files automatically:
143
144 .. code-block:: pycon
145
146 >>> from django.core.files import File
147
148 # Create a Python file object using open() and the with statement
149 >>> with open("/path/to/hello.world", "w") as f:
150 ... myfile = File(f)
151 ... myfile.write("Hello World")
152 ...
153 >>> myfile.closed
154 True
155 >>> f.closed
156 True
157
158 Closing files is especially important when accessing file fields in a loop
159 over a large number of objects. If files are not manually closed after
160 accessing them, the risk of running out of file descriptors may arise. This
161 may lead to the following error:
162
163 .. code-block:: pytb
164
165 OSError: [Errno 24] Too many open files
166
167
168 File storage
169 ============
170
171 Behind the scenes, Django delegates decisions about how and where to store files
172 to a file storage system. This is the object that actually understands things
173 like file systems, opening and reading files, etc.
174
175 Django's default file storage is
176 ``'``:class:`django.core.files.storage.FileSystemStorage`\ ``'``. If you don't
177 explicitly provide a storage system in the ``default`` key of the
178 :setting:`STORAGES` setting, this is the one that will be used.
179
180 See below for details of the built-in default file storage system, and see
181 :doc:`/howto/custom-file-storage` for information on writing your own file
182 storage system.
183
184 Storage objects
185 ---------------
186
187 Though most of the time you'll want to use a ``File`` object (which delegates to
188 the proper storage for that file), you can use file storage systems directly.
189 You can create an instance of some custom file storage class, or -- often more
190 useful -- you can use the global default storage system:
191
192 .. code-block:: pycon
193
194 >>> from django.core.files.base import ContentFile
195 >>> from django.core.files.storage import default_storage
196
197 >>> path = default_storage.save("path/to/file", ContentFile(b"new content"))
198 >>> path
199 'path/to/file'
200
201 >>> default_storage.size(path)
202 11
203 >>> default_storage.open(path).read()
204 b'new content'
205
206 >>> default_storage.delete(path)
207 >>> default_storage.exists(path)
208 False
209
210 See :doc:`/ref/files/storage` for the file storage API.
211
212 .. _builtin-fs-storage:
213
214 The built-in filesystem storage class
215 -------------------------------------
216
217 Django ships with a :class:`django.core.files.storage.FileSystemStorage` class
218 which implements basic local filesystem file storage.
219
220 For example, the following code will store uploaded files under
221 ``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::
222
223 from django.core.files.storage import FileSystemStorage
224 from django.db import models
225
226 fs = FileSystemStorage(location="/media/photos")
227
228
229 class Car(models.Model):
230 ...
231 photo = models.ImageField(storage=fs)
232
233 :doc:`Custom storage systems </howto/custom-file-storage>` work the same way:
234 you can pass them in as the ``storage`` argument to a
235 :class:`~django.db.models.FileField`.
236
237 Using a callable
238 ----------------
239
240 You can use a callable as the :attr:`~django.db.models.FileField.storage`
241 parameter for :class:`~django.db.models.FileField` or
242 :class:`~django.db.models.ImageField`. This allows you to modify the used
243 storage at runtime, selecting different storages for different environments,
244 for example.
245
246 Your callable will be evaluated when your models classes are loaded, and must
247 return an instance of :class:`~django.core.files.storage.Storage`.
248
249 For example::
250
251 from django.conf import settings
252 from django.db import models
253 from .storages import MyLocalStorage, MyRemoteStorage
254
255
256 def select_storage():
257 return MyLocalStorage() if settings.DEBUG else MyRemoteStorage()
258
259
260 class MyModel(models.Model):
261 my_file = models.FileField(storage=select_storage)
262
263 In order to set a storage defined in the :setting:`STORAGES` setting you can
264 use :data:`~django.core.files.storage.storages`::
265
266 from django.core.files.storage import storages
267
268
269 def select_storage():
270 return storages["mystorage"]
271
272
273 class MyModel(models.Model):
274 upload = models.FileField(storage=select_storage)
275
276 Because the callable is evaluated when your models classes are loaded, if you
277 need to override the :setting:`STORAGES` setting in tests, you should use a
278 ``LazyObject`` subclass instead::
279
280 from django.core.files.storage import storages
281 from django.utils.functional import LazyObject
282
283
284 class OtherStorage(LazyObject):
285 def _setup(self):
286 self._wrapped = storages["mystorage"]
287
288
289 my_storage = OtherStorage()
290
291
292 class MyModel(models.Model):
293 upload = models.FileField(storage=my_storage)
294
295 The ``LazyObject`` delays the evaluation of the storage until it's actually
296 needed, allowing :func:`~django.test.override_settings` to take effect::
297
298 @override_settings(
299 STORAGES={
300 "mystorage": {
301 "BACKEND": "django.core.files.storage.InMemoryStorage",
302 }
303 }
304 )
305 def test_storage():
306 model = MyModel()
307 assert isinstance(model.upload.storage, InMemoryStorage)