Debian Codegraph @

docs/ref/files/file.txt

raw
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.