Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #13162 and #11597 -- Improved the file handling documentation: …

…Removed documentation of methods on django.core.files.File that did not exist, added documentation for undocumented methods and attributes that did exist, did a general cleanup of the text and organization, and added more metadata targets. Thanks to amenasse and tyrion.mx for the reports.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14833 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 2dd594dff4f68f36b345f454738c35f01e5dd48e 1 parent 0ab50aa
Gabriel Hurley authored
View
132 docs/ref/files/file.txt
@@ -1,56 +1,54 @@
The ``File`` object
===================
-.. currentmodule:: django.core.files
+The :mod:`django.core.files` module and its submodules contain built-in classes
+for basic file handling in Django.
-``File`` attributes and methods
--------------------------------
+.. currentmodule:: django.core.files
-The :mod:`django.core.files` module contains a built-in class for basic file
-handling in Django. The :class:`File` class has the following attributes and
-methods:
+The ``File`` Class
+------------------
.. class:: File(file_object)
- .. attribute:: name
-
- The name of file including the relative path from :setting:`MEDIA_ROOT`.
+ The :class:`File` is a thin wrapper around Python's built-in file object
+ with some Django-specific additions. Internally, Django uses this class
+ any time it needs to represent a file.
+
+ :class:`File` objects have the following attributes and methods:
- .. attribute:: path
-
- The absolute path to the file's location on a local filesystem.
+ .. attribute:: name
- :doc:`Custom file storage systems </howto/custom-file-storage>` may not store
- files locally; files stored on these systems will have a ``path`` of
- ``None``.
+ The name of file including the relative path from
+ :setting:`MEDIA_ROOT`.
- .. attribute:: url
+ .. attribute:: size
- The URL where the file can be retrieved. This is often useful in
- :doc:`templates </topics/templates>`; for example, a bit of a template for
- displaying a ``Car`` (see above) might look like:
+ The size of the file in bytes.
- .. code-block:: html+django
+ .. attribute:: file
- <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
+ The underlying Python ``file`` object passed to
+ :class:`~django.core.files.File`.
- .. attribute:: size
+ .. attribute:: mode
- The size of the file in bytes.
+ The read/write mode for the file.
.. method:: 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()``.
+ 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.
+ When reopening a file, ``mode`` will override whatever mode the file
+ was originally opened with; ``None`` means to reopen with the original
+ mode.
.. method:: 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.
+ 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.
.. method:: __iter__()
@@ -61,38 +59,65 @@ methods:
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.
+ 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.
.. method:: 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``.
+ Returns ``True`` if the file is large enough to require multiple chunks
+ to access all of its content give some ``chunk_size``.
.. method:: 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.
+ 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.
.. method:: close()
Close the file.
+ In addition to the listed methods, :class:`~django.core.files.File` exposes
+ the following attributes and methods of the underlying ``file`` object:
+ ``encoding``, ``fileno``, ``flush``, ``isatty``, ``newlines``,
+ ``read``, ``readinto``, ``readlines``, ``seek``, ``softspace``, ``tell``,
+ ``truncate``, ``writelines``, ``xreadlines``.
+
+.. currentmodule:: django.core.files.base
+
+The ``ContentFile`` Class
+-------------------------
+
+.. class:: ContentFile(File)
+
+ The ``ContentFile`` class inherits from :class:`~django.core.files.File`,
+ but unlike :class:`~django.core.files.File` it operates on string content,
+ rather than an actual file. For example::
+
+ from django.core.files.base import ContentFile
+
+ f1 = ContentFile("my string content")
+ f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8'))
+
.. currentmodule:: django.core.files.images
-Additional ``ImageFile`` attributes
-------------------------------------
+The ``ImageFile`` Class
+-----------------------
.. class:: ImageFile(file_object)
+ Django provides a built-in class specifically for images.
+ :class:`django.core.files.images.ImageFile` inherits all the attributes
+ and methods of :class:`~django.core.files.File`, and additionally
+ provides the following:
+
.. attribute:: width
- Width of the image.
+ Width of the image in pixels.
.. attribute:: height
- Height of the image.
+ Height of the image in pixels.
.. currentmodule:: django.core.files
@@ -100,7 +125,7 @@ Additional methods on files attached to objects
-----------------------------------------------
Any :class:`File` that's associated with an object (as with ``Car.photo``,
-above) will also have a couple of extra methods:
+below) will also have a couple of extra methods:
.. method:: File.save(name, content, [save=True])
@@ -116,23 +141,12 @@ above) will also have a couple of extra methods:
>>> 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` such as :class:`ContentFile`.
+ Note that the ``content`` argument must be an instance of either
+ :class:`File` or of a subclass of :class:`File`, such as
+ :class:`ContentFile`.
.. method:: File.delete([save=True])
- Remove the file from the model instance and delete the underlying file. The
- ``save`` argument works as above.
-
-``ContentFile`` objects
------------------------
-
-.. class:: ContentFile(File)
-
-A ``ContentFile`` is a File-like object that takes string content, rather
-than an actual file::
-
- from django.core.files.base import ContentFile
-
- f1 = ContentFile("my string content")
- f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8'))
+ 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.
View
2  docs/ref/files/index.txt
@@ -6,7 +6,7 @@ File handling
:synopsis: File handling and storage
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
file
storage
View
10 docs/topics/files.txt
@@ -50,9 +50,9 @@ it has all the methods and attributes described below.
The ``File`` object
===================
-Internally, Django uses a ``django.core.files.File`` any time it needs to
-represent a file. This object is a thin wrapper around Python's `built-in file
-object`_ with some Django-specific additions.
+Internally, Django uses a :class:`django.core.files.File` instance any time it
+needs to represent a file. This object is a thin wrapper around Python's
+`built-in file object`_ with some Django-specific additions.
.. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects
@@ -68,8 +68,8 @@ using a Python built-in ``file`` object::
>>> f = open('/tmp/hello.world', 'w')
>>> myfile = File(f)
-Now you can use any of the ``File`` attributes and methods documented in
-:doc:`/ref/files/file`.
+Now you can use any of the documented attributes and methods
+of the :class:`~django.core.files.File` class.
File storage
============
Please sign in to comment.
Something went wrong with that request. Please try again.