1 The ``File`` object

     2 ===================

     3 

     4 The :mod:`django.core.files` module and its submodules contain built-in classes

     5 for basic file handling in Django.

     6 

     7 .. currentmodule:: django.core.files

     8 

     9 The ``File`` Class

    10 ------------------

    11 

    12 .. class:: File(file_object)

    13 

    14     The :class:`File` is a thin wrapper around Python's built-in file object

    15     with some Django-specific additions. Internally, Django uses this class

    16     any time it needs to represent a file.

    17     

    18     :class:`File` objects have the following attributes and methods:

    19 

    20     .. attribute:: name

    21 

    22         The name of file including the relative path from

    23         :setting:`MEDIA_ROOT`.

    24 

    25     .. attribute:: size

    26 

    27         The size of the file in bytes.

    28 

    29     .. attribute:: file

    30 

    31         The underlying Python ``file`` object passed to

    32         :class:`~django.core.files.File`.

    33 

    34     .. attribute:: mode

    35 

    36         The read/write mode for the file.

    37 

    38     .. method:: open([mode=None])

    39 

    40         Open or reopen the file (which by definition also does

    41         ``File.seek(0)``). The ``mode`` argument allows the same values

    42         as Python's standard ``open()``.

    43 

    44         When reopening a file, ``mode`` will override whatever mode the file

    45         was originally opened with; ``None`` means to reopen with the original

    46         mode.

    47 

    48     .. method:: read([num_bytes=None])

    49 

    50         Read content from the file. The optional ``size`` is the number of

    51         bytes to read; if not specified, the file will be read to the end.

    52 

    53     .. method:: __iter__()

    54 

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

    56 

    57     .. method:: chunks([chunk_size=None])

    58 

    59         Iterate over the file yielding "chunks" of a given size. ``chunk_size``

    60         defaults to 64 KB.

    61 

    62         This is especially useful with very large files since it allows them to

    63         be streamed off disk and avoids storing the whole file in memory.

    64 

    65     .. method:: multiple_chunks([chunk_size=None])

    66 

    67         Returns ``True`` if the file is large enough to require multiple chunks

    68         to access all of its content give some ``chunk_size``.

    69 

    70     .. method:: write([content])

    71 

    72         Writes the specified content string to the file. Depending on the

    73         storage system behind the scenes, this content might not be fully

    74         committed until ``close()`` is called on the file.

    75 

    76     .. method:: close()

    77 

    78         Close the file.

    79 

    80     In addition to the listed methods, :class:`~django.core.files.File` exposes

    81     the following attributes and methods of the underlying ``file`` object:

    82     ``encoding``, ``fileno``, ``flush``, ``isatty``, ``newlines``,

    83     ``read``, ``readinto``, ``readlines``, ``seek``, ``softspace``, ``tell``,

    84     ``truncate``, ``writelines``, ``xreadlines``.

    85 

    86 .. currentmodule:: django.core.files.base

    87 

    88 The ``ContentFile`` Class

    89 -------------------------

    90 

    91 .. class:: ContentFile(File)

    92 

    93     The ``ContentFile`` class inherits from :class:`~django.core.files.File`,

    94     but unlike :class:`~django.core.files.File` it operates on string content,

    95     rather than an actual file. For example::

    96 

    97         from django.core.files.base import ContentFile

    98 

    99         f1 = ContentFile("my string content")

   100         f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8'))

   101 

   102 .. currentmodule:: django.core.files.images

   103 

   104 The ``ImageFile`` Class

   105 -----------------------

   106 

   107 .. class:: ImageFile(file_object)

   108 

   109     Django provides a built-in class specifically for images.

   110     :class:`django.core.files.images.ImageFile` inherits all the attributes

   111     and methods of :class:`~django.core.files.File`, and additionally

   112     provides the following:

   113 

   114     .. attribute:: width

   115 

   116         Width of the image in pixels.

   117 

   118     .. attribute:: height

   119 

   120         Height of the image in pixels.

   121 

   122 .. currentmodule:: django.core.files

   123 

   124 Additional methods on files attached to objects

   125 -----------------------------------------------

   126 

   127 Any :class:`File` that's associated with an object (as with ``Car.photo``,

   128 below) will also have a couple of extra methods:

   129 

   130 .. method:: File.save(name, content, [save=True])

   131 

   132     Saves a new file with the file name and contents provided. This will not

   133     replace the existing file, but will create a new file and update the object

   134     to point to it. If ``save`` is ``True``, the model's ``save()`` method will

   135     be called once the file is saved. That is, these two lines::

   136 

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

   138         >>> car.save()

   139 

   140     are the same as this one line::

   141 

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

   143 

   144     Note that the ``content`` argument must be an instance of either

   145     :class:`File` or of a subclass of :class:`File`, such as

   146     :class:`ContentFile`.

   147 

   148 .. method:: File.delete([save=True])

   149 

   150     Removes the file from the model instance and deletes the underlying file.

   151     If ``save`` is ``True``, the model's ``save()`` method will be called once

   152     the file is deleted.