PageRenderTime 10ms CodeModel.GetById 2ms app.highlight 2ms RepoModel.GetById 2ms app.codeStats 0ms

/docs/ref/files/file.txt

https://code.google.com/p/mango-py/
Plain Text | 152 lines | 96 code | 56 blank | 0 comment | 0 complexity | ae8fd017f1b41a2f35e0a2e6f2378529 MD5 | raw file
  1The ``File`` object
  2===================
  3
  4The :mod:`django.core.files` module and its submodules contain built-in classes
  5for basic file handling in Django.
  6
  7.. currentmodule:: django.core.files
  8
  9The ``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
 88The ``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
104The ``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
124Additional methods on files attached to objects
125-----------------------------------------------
126
127Any :class:`File` that's associated with an object (as with ``Car.photo``,
128below) 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.