The File
object¶
The django.core.files
module and its submodules contain built-in classes
for basic file handling in Django.
The File
Class¶
-
class
File
(file_object)¶ The
File
is a thin wrapper around Python’s built-in file object with some Django-specific additions. Internally, Django uses this class any time it needs to represent a file.File
objects have the following attributes and methods:-
name
¶ The name of file including the relative path from
MEDIA_ROOT
.
-
size
¶ The size of the file in bytes.
-
mode
¶ The read/write mode for the file.
-
open
([mode=None])¶ Open or reopen the file (which by definition also does
File.seek(0)
). Themode
argument allows the same values as Python’s standardopen()
.When reopening a file,
mode
will override whatever mode the file was originally opened with;None
means to reopen with the original mode.
-
read
([num_bytes=None])¶ Read content from the file. The optional
size
is the number of bytes to read; if not specified, the file will be read to the end.
-
__iter__
()¶ Iterate over the file yielding one line at a time.
-
chunks
([chunk_size=None])¶ Iterate over the file yielding “chunks” of a given size.
chunk_size
defaults to 64 KB.This is especially useful with very large files since it allows them to be streamed off disk and avoids storing the whole file in memory.
-
multiple_chunks
([chunk_size=None])¶ Returns
True
if the file is large enough to require multiple chunks to access all of its content give somechunk_size
.
-
write
([content])¶ Writes the specified content string to the file. Depending on the storage system behind the scenes, this content might not be fully committed until
close()
is called on the file.
-
close
()¶ Close the file.
In addition to the listed methods,
File
exposes the following attributes and methods of the underlyingfile
object:encoding
,fileno
,flush
,isatty
,newlines
,read
,readinto
,readlines
,seek
,softspace
,tell
,truncate
,writelines
,xreadlines
.-
The ContentFile
Class¶
-
class
ContentFile
(File)¶ The
ContentFile
class inherits fromFile
, but unlikeFile
it operates on string content (bytes also supported), rather than an actual file. For example:from __future__ import unicode_literals from django.core.files.base import ContentFile f1 = ContentFile("esta sentencia está en español") f2 = ContentFile(b"these are bytes")
The ImageFile
Class¶
-
class
ImageFile
(file_object)¶ Django provides a built-in class specifically for images.
django.core.files.images.ImageFile
inherits all the attributes and methods ofFile
, and additionally provides the following:-
width
¶ Width of the image in pixels.
-
height
¶ Height of the image in pixels.
-
Additional methods on files attached to objects¶
Any File
that’s associated with an object (as with Car.photo
,
below) will also have a couple of extra methods:
-
File.
save
(name, content[, save=True])¶ Saves a new file with the file name and contents provided. This will not replace the existing file, but will create a new file and update the object to point to it. If
save
isTrue
, the model’ssave()
method will be called once the file is saved. That is, these two lines:>>> car.photo.save('myphoto.jpg', content, save=False) >>> car.save()
are the same as this one line:
>>> car.photo.save('myphoto.jpg', content, save=True)
Note that the
content
argument must be an instance of eitherFile
or of a subclass ofFile
, such asContentFile
.
-
File.
delete
([save=True])¶ Removes the file from the model instance and deletes the underlying file. If
save
isTrue
, the model’ssave()
method will be called once the file is deleted.