PageRenderTime 24ms CodeModel.GetById 0ms RepoModel.GetById 0ms app.codeStats 0ms

Plain Text | 152 lines | 96 code | 56 blank | 0 comment | 0 complexity | ae8fd017f1b41a2f35e0a2e6f2378529 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. The ``File`` object
  2. ===================
  3. The :mod:`django.core.files` module and its submodules contain built-in classes
  4. for basic file handling in Django.
  5. .. currentmodule:: django.core.files
  6. The ``File`` Class
  7. ------------------
  8. .. class:: File(file_object)
  9. The :class:`File` is a thin wrapper around Python's built-in file object
  10. with some Django-specific additions. Internally, Django uses this class
  11. any time it needs to represent a file.
  12. :class:`File` objects have the following attributes and methods:
  13. .. attribute:: name
  14. The name of file including the relative path from
  15. :setting:`MEDIA_ROOT`.
  16. .. attribute:: size
  17. The size of the file in bytes.
  18. .. attribute:: file
  19. The underlying Python ``file`` object passed to
  20. :class:`~django.core.files.File`.
  21. .. attribute:: mode
  22. The read/write mode for the file.
  23. .. method:: open([mode=None])
  24. Open or reopen the file (which by definition also does
  25. ````). The ``mode`` argument allows the same values
  26. as Python's standard ``open()``.
  27. When reopening a file, ``mode`` will override whatever mode the file
  28. was originally opened with; ``None`` means to reopen with the original
  29. mode.
  30. .. method:: read([num_bytes=None])
  31. Read content from the file. The optional ``size`` is the number of
  32. bytes to read; if not specified, the file will be read to the end.
  33. .. method:: __iter__()
  34. Iterate over the file yielding one line at a time.
  35. .. method:: chunks([chunk_size=None])
  36. Iterate over the file yielding "chunks" of a given size. ``chunk_size``
  37. defaults to 64 KB.
  38. This is especially useful with very large files since it allows them to
  39. be streamed off disk and avoids storing the whole file in memory.
  40. .. method:: multiple_chunks([chunk_size=None])
  41. Returns ``True`` if the file is large enough to require multiple chunks
  42. to access all of its content give some ``chunk_size``.
  43. .. method:: write([content])
  44. Writes the specified content string to the file. Depending on the
  45. storage system behind the scenes, this content might not be fully
  46. committed until ``close()`` is called on the file.
  47. .. method:: close()
  48. Close the file.
  49. In addition to the listed methods, :class:`~django.core.files.File` exposes
  50. the following attributes and methods of the underlying ``file`` object:
  51. ``encoding``, ``fileno``, ``flush``, ``isatty``, ``newlines``,
  52. ``read``, ``readinto``, ``readlines``, ``seek``, ``softspace``, ``tell``,
  53. ``truncate``, ``writelines``, ``xreadlines``.
  54. .. currentmodule:: django.core.files.base
  55. The ``ContentFile`` Class
  56. -------------------------
  57. .. class:: ContentFile(File)
  58. The ``ContentFile`` class inherits from :class:`~django.core.files.File`,
  59. but unlike :class:`~django.core.files.File` it operates on string content,
  60. rather than an actual file. For example::
  61. from django.core.files.base import ContentFile
  62. f1 = ContentFile("my string content")
  63. f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8'))
  64. .. currentmodule:: django.core.files.images
  65. The ``ImageFile`` Class
  66. -----------------------
  67. .. class:: ImageFile(file_object)
  68. Django provides a built-in class specifically for images.
  69. :class:`django.core.files.images.ImageFile` inherits all the attributes
  70. and methods of :class:`~django.core.files.File`, and additionally
  71. provides the following:
  72. .. attribute:: width
  73. Width of the image in pixels.
  74. .. attribute:: height
  75. Height of the image in pixels.
  76. .. currentmodule:: django.core.files
  77. Additional methods on files attached to objects
  78. -----------------------------------------------
  79. Any :class:`File` that's associated with an object (as with ````,
  80. below) will also have a couple of extra methods:
  81. .. method::, content, [save=True])
  82. Saves a new file with the file name and contents provided. This will not
  83. replace the existing file, but will create a new file and update the object
  84. to point to it. If ``save`` is ``True``, the model's ``save()`` method will
  85. be called once the file is saved. That is, these two lines::
  86. >>>'myphoto.jpg', contents, save=False)
  87. >>>
  88. are the same as this one line::
  89. >>>'myphoto.jpg', contents, save=True)
  90. Note that the ``content`` argument must be an instance of either
  91. :class:`File` or of a subclass of :class:`File`, such as
  92. :class:`ContentFile`.
  93. .. method:: File.delete([save=True])
  94. Removes the file from the model instance and deletes the underlying file.
  95. If ``save`` is ``True``, the model's ``save()`` method will be called once
  96. the file is deleted.