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