[1.2.X] Fixed #13162 and #11597 -- Improved the file handling documen…

…tation: 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.

Backport of [14833] from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14834 bcc190cf-cafb-0310-a4f2-bffc1f526a37

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,46 +59,73 @@ 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
 
 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.

docs/ref/files/index.txt

@@ -6,7 +6,7 @@ File handling
    :synopsis: File handling and storage
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    file
    storage

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
 ============