.. _ref-files-file:

The ``File`` object
===================

.. currentmodule:: django.core.files

.. class:: File(file_object)

``File`` attributes and methods
-------------------------------

Django's ``File`` has the following attributes and methods:

``File.path``
~~~~~~~~~~~~~

The absolute path to the file's location on a local filesystem.

:ref:`Custom file storage systems <howto-custom-file-storage>` may not store
files locally; files stored on these systems will have a ``path`` of ``None``.

``File.url``
~~~~~~~~~~~~

The URL where the file can be retrieved. This is often useful in :ref:`templates
<topics-templates>`; for example, a bit of a template for displaying a ``Car``
(see above) might look like::

    <img src='{{ car.photo.url }}' alt='{{ car.name }}' />

``File.size``
~~~~~~~~~~~~~

The size of the file in bytes.

``File.open(mode=None)``
~~~~~~~~~~~~~~~~~~~~~~~~

Open or reopen the file (which by definition also does ``File.seek(0)``). The
``mode`` argument allows the same values as Python's standard ``open()``.

When reopening a file, ``mode`` will override whatever mode the file was
originally opened with; ``None`` means to reopen with the original mode.

``File.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.

``File.__iter__()``
~~~~~~~~~~~~~~~~~~~

Iterate over the file yielding one line at a time.

``File.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.

``File.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``.

``File.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.

``File.close()``
~~~~~~~~~~~~~~~~

Close the file.

Additional ``ImageField`` attributes
------------------------------------

``File.width`` and ``File.height``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These attributes provide the dimensions of the image.

Additional methods on files attached to objects
-----------------------------------------------

Any ``File`` that's associated with an object (as with ``Car.photo``, above)
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', contents, save=False)
    >>> car.save()

are the same as this one line::

    >>> car.photo.save('myphoto.jpg', contents, save=True)

Note that the ``content`` argument must be an instance of
:class:`File` or of a subclass of :class:`File`.

``File.delete(save=True)``
~~~~~~~~~~~~~~~~~~~~~~~~~~

Remove the file from the model instance and delete the underlying file. The
``save`` argument works as above.