| 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) |