# Django 1.8.18.dev20170123152445 documentation

# 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` 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)

    Open or reopen the file (which also does `File.seek(0)`). The `mode` argument allows the same values as Python’s built-in `open()`.

    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.

    `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)

    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 some `chunk_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 its `file` 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 from `File`, but unlike `File` 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 of `File`, 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` is `True`, the model’s `save()` 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 either `File` or of a subclass of `File`, such as `ContentFile`.

`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 once the file is deleted.