The File object

The django.core.files module and its submodules contain built-in classesfor basic file handling in Django.

The File class

• class File(file_object)[源代码]
• The File class is a thin wrapper around a Pythonfile 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 fromMEDIA_ROOT.

• size

• The size of the file in bytes.

• file

• The underlying file object that this class wraps.

Be careful with this attribute in subclasses.

Some subclasses of File, includingContentFile andFieldFile, may replace thisattribute with an object other than a Python file object.In these cases, this attribute may itself be a Filesubclass (and not necessarily the same subclass). Wheneverpossible, use the attributes and methods of the subclass itselfrather than the those of the subclass's file attribute.

• mode

• The read/write mode for the file.

• open(mode=None)[源代码]

• Open or reopen the file (which also does File.seek(0)).The mode argument allows the same valuesas Python's built-in open().

When reopening a file, mode will override whatever mode the filewas originally opened with; None means to reopen with the originalmode.

It can be used as a context manager, e.g. with file.open() as f:.

• 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_sizedefaults to 64 KB.

This is especially useful with very large files since it allows them tobe streamed off disk and avoids storing the whole file in memory.

• multiplechunks(_chunk_size=None)[源代码]

• Returns True if the file is large enough to require multiple chunksto access all of its content give some chunk_size.

• close()[源代码]

• Close the file.

In addition to the listed methods, File exposesthe following attributes and methods of its file object:encoding, fileno, flush, isatty, newlines, read,readinto, readline, readlines, seek, tell,truncate, write, writelines, readable(), writable(),and seekable().

The ContentFile class

• class ContentFile(File)[源代码]
• The ContentFile class inherits from File,but unlike File it operates on string content(bytes also supported), rather than an actual file. For example:

from django.core.files.base import ContentFile
 
f1 = ContentFile("esta frase 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 attributesand methods of File, and additionallyprovides 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 notreplace the existing file, but will create a new file and update the objectto point to it. If save is True, the model's save() method willbe 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 of File, such asContentFile.

• File.delete(save=True)
• Removes the file from the model instance and deletes the underlying file.If save is True, the model's save() method will be called oncethe file is deleted.