| 1 |
=================== |
| 2 |
The ``File`` object |
| 3 |
=================== |
| 4 |
|
| 5 |
The :mod:`django.core.files` module and its submodules contain built-in classes |
| 6 |
for basic file handling in Django. |
| 7 |
|
| 8 |
.. currentmodule:: django.core.files |
| 9 |
|
| 10 |
The ``File`` class |
| 11 |
================== |
| 12 |
|
| 13 |
.. class:: File(file_object, name=None) |
| 14 |
|
| 15 |
The :class:`File` class is a thin wrapper around a Python |
| 16 |
:py:term:`file object` with some Django-specific additions. |
| 17 |
Internally, Django uses this class when it needs to represent a file. |
| 18 |
|
| 19 |
:class:`File` objects have the following attributes and methods: |
| 20 |
|
| 21 |
.. attribute:: name |
| 22 |
|
| 23 |
The name of the file including the relative path from |
| 24 |
:setting:`MEDIA_ROOT`. |
| 25 |
|
| 26 |
.. attribute:: size |
| 27 |
|
| 28 |
The size of the file in bytes. |
| 29 |
|
| 30 |
.. attribute:: file |
| 31 |
|
| 32 |
The underlying :py:term:`file object` that this class wraps. |
| 33 |
|
| 34 |
.. admonition:: Be careful with this attribute in subclasses. |
| 35 |
|
| 36 |
Some subclasses of :class:`File`, including |
| 37 |
:class:`~django.core.files.base.ContentFile` and |
| 38 |
:class:`~django.db.models.fields.files.FieldFile`, may replace this |
| 39 |
attribute with an object other than a Python :py:term:`file object`. |
| 40 |
In these cases, this attribute may itself be a :class:`File` |
| 41 |
subclass (and not necessarily the same subclass). Whenever |
| 42 |
possible, use the attributes and methods of the subclass itself |
| 43 |
rather than the those of the subclass's ``file`` attribute. |
| 44 |
|
| 45 |
.. attribute:: mode |
| 46 |
|
| 47 |
The read/write mode for the file. |
| 48 |
|
| 49 |
.. method:: open(mode=None, *args, **kwargs) |
| 50 |
|
| 51 |
Open or reopen the file (which also does ``File.seek(0)``). |
| 52 |
The ``mode`` argument allows the same values |
| 53 |
as Python's built-in :func:`python:open()`. ``*args`` and ``**kwargs`` |
| 54 |
are passed after ``mode`` to Python's built-in :func:`python:open`. |
| 55 |
|
| 56 |
When reopening a file, ``mode`` will override whatever mode the file |
| 57 |
was originally opened with; ``None`` means to reopen with the original |
| 58 |
mode. |
| 59 |
|
| 60 |
It can be used as a context manager, e.g. ``with file.open() as f:``. |
| 61 |
|
| 62 |
.. method:: __iter__() |
| 63 |
|
| 64 |
Iterate over the file yielding one line at a time. |
| 65 |
|
| 66 |
.. method:: chunks(chunk_size=None) |
| 67 |
|
| 68 |
Iterate over the file yielding "chunks" of a given size. ``chunk_size`` |
| 69 |
defaults to 64 KB. |
| 70 |
|
| 71 |
This is especially useful with very large files since it allows them to |
| 72 |
be streamed off disk and avoids storing the whole file in memory. |
| 73 |
|
| 74 |
.. method:: multiple_chunks(chunk_size=None) |
| 75 |
|
| 76 |
Returns ``True`` if the file is large enough to require multiple chunks |
| 77 |
to access all of its content give some ``chunk_size``. |
| 78 |
|
| 79 |
.. method:: close() |
| 80 |
|
| 81 |
Close the file. |
| 82 |
|
| 83 |
In addition to the listed methods, :class:`~django.core.files.File` exposes |
| 84 |
the following attributes and methods of its ``file`` object: |
| 85 |
``encoding``, ``fileno``, ``flush``, ``isatty``, ``newlines``, ``read``, |
| 86 |
``readinto``, ``readline``, ``readlines``, ``seek``, ``tell``, |
| 87 |
``truncate``, ``write``, ``writelines``, ``readable()``, ``writable()``, |
| 88 |
and ``seekable()``. |
| 89 |
|
| 90 |
.. currentmodule:: django.core.files.base |
| 91 |
|
| 92 |
The ``ContentFile`` class |
| 93 |
========================= |
| 94 |
|
| 95 |
.. class:: ContentFile(content, name=None) |
| 96 |
|
| 97 |
The ``ContentFile`` class inherits from :class:`~django.core.files.File`, |
| 98 |
but unlike :class:`~django.core.files.File` it operates on string content |
| 99 |
(bytes also supported), rather than an actual file. For example:: |
| 100 |
|
| 101 |
from django.core.files.base import ContentFile |
| 102 |
|
| 103 |
f1 = ContentFile("esta frase está en español") |
| 104 |
f2 = ContentFile(b"these are bytes") |
| 105 |
|
| 106 |
.. currentmodule:: django.core.files.images |
| 107 |
|
| 108 |
The ``ImageFile`` class |
| 109 |
======================= |
| 110 |
|
| 111 |
.. class:: ImageFile(file_object, name=None) |
| 112 |
|
| 113 |
Django provides a built-in class specifically for images. |
| 114 |
:class:`django.core.files.images.ImageFile` inherits all the attributes |
| 115 |
and methods of :class:`~django.core.files.File`, and additionally |
| 116 |
provides the following: |
| 117 |
|
| 118 |
.. attribute:: width |
| 119 |
|
| 120 |
Width of the image in pixels. |
| 121 |
|
| 122 |
.. attribute:: height |
| 123 |
|
| 124 |
Height of the image in pixels. |
| 125 |
|
| 126 |
.. currentmodule:: django.core.files |
| 127 |
|
| 128 |
Additional methods on files attached to objects |
| 129 |
=============================================== |
| 130 |
|
| 131 |
Any :class:`File` that is associated with an object (as with ``Car.photo``, |
| 132 |
below) will also have a couple of extra methods: |
| 133 |
|
| 134 |
.. method:: File.save(name, content, save=True) |
| 135 |
|
| 136 |
Saves a new file with the file name and contents provided. This will not |
| 137 |
replace the existing file, but will create a new file and update the object |
| 138 |
to point to it. If ``save`` is ``True``, the model's ``save()`` method will |
| 139 |
be called once the file is saved. That is, these two lines: |
| 140 |
|
| 141 |
.. code-block:: pycon |
| 142 |
|
| 143 |
>>> car.photo.save("myphoto.jpg", content, save=False) |
| 144 |
>>> car.save() |
| 145 |
|
| 146 |
are equivalent to: |
| 147 |
|
| 148 |
.. code-block:: pycon |
| 149 |
|
| 150 |
>>> car.photo.save("myphoto.jpg", content, save=True) |
| 151 |
|
| 152 |
Note that the ``content`` argument must be an instance of either |
| 153 |
:class:`File` or of a subclass of :class:`File`, such as |
| 154 |
:class:`~django.core.files.base.ContentFile`. |
| 155 |
|
| 156 |
.. method:: File.delete(save=True) |
| 157 |
|
| 158 |
Removes the file from the model instance and deletes the underlying file. |
| 159 |
If ``save`` is ``True``, the model's ``save()`` method will be called once |
| 160 |
the file is deleted. |