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)[source]
  • 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)[source]

  • 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:.

Changed in Django 2.0:Context manager support was added.

  • iter()[source]

  • Iterate over the file yielding one line at a time.

  • chunks(chunk_size=None)[source]

  • 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)[source]

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

  • close()[source]

  • 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().

Changed in Django 1.11:The readable() and writable() methods were added.

The ContentFile class

  • class ContentFile(File)[source]
  • The ContentFile class inherits from File,but unlike File it operates on string content(bytes also supported), rather than an actual file. For example:
  1. from django.core.files.base import ContentFile
  2.  
  3. f1 = ContentFile("esta sentencia está en español")
  4. 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 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:
  1. >>> car.photo.save('myphoto.jpg', content, save=False)
  2. >>> car.save()

are equivalent to:

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