The File object
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)
[source] -
The
File
class is a thin wrapper around a Python file object with some Django-specific additions. Internally, Django uses this class when it needs to represent a file.File
objects have the following attributes and methods:-
name
-
The name of the file including the relative path from
MEDIA_ROOT
.
-
size
-
The size of the file in bytes.
-
file
-
The underlying file object that this class wraps.
-
mode
-
The read/write mode for the file.
-
open(mode=None)
[source] -
Open or reopen the file (which also does
File.seek(0)
). Themode
argument allows the same values as Python’s built-inopen()
.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__()
[source] -
Iterate over the file yielding one line at a time.
File
now uses universal newlines. The following are recognized as ending a line: the Unix end-of-line convention'\n'
, the Windows convention'\r\n'
, and the old Macintosh convention'\r'
.
-
chunks(chunk_size=None)
[source] -
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)
[source] -
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()
[source] -
Close the file.
In addition to the listed methods,
File
exposes the following attributes and methods of itsfile
object:encoding
,fileno
,flush
,isatty
,newlines
,read
,readinto
,readlines
,seek
,softspace
,tell
,truncate
,writelines
,xreadlines
. -
The ContentFile
Class
-
class ContentFile(File)
[source] -
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)
[source] -
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 is 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 equivalent to:
>>> 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.
© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/1.8/ref/files/file/