Ticket #12229: 12229_filefield_docs_patch.diff

docs/ref/models/fields.txt

@@ -572 +572 @@
 
 .. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime
 
+FileField and FieldFile
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Internally, :class:`FileField` instances use a utility class called 
+:class:`FieldFile` to handle the connection between the underlying file and 
+the field instance's attributes. In general you won't need to work with the 
+:class:`FieldFile` class directly, however several convenience methods on 
+:class:`FieldFile` are exposed for general usage when you use a 
+:class:`FileField` on your model:
+
+.. method:: FieldFile.open(mode='rb')
+
+Behaves like the standard Python ``open()`` method and opens the file 
+associated with this instance in the mode specified by ``mode``.
+
+.. method:: FieldFile.close()
+
+Behaves like the standard Python ``file.close()`` method and closes the file 
+associated with this instance.
+
+.. method:: FieldFile.save(name, content, save=True)
+
+This method takes a filename and file contents and passes them to the storage 
+class for this instance, then associates the stored file with this 
+instance. If you want to manually associate files with :class:`FileField` 
+instances on your model, this is the method to use.
+
+Takes two required arguments: ``name`` which is the name of the file, and 
+``content`` which is a file-like object containing the file's contents. The 
+optional ``save`` argument controls whether or not the instance is saved after 
+the file has been altered. Defaults to ``True``.
+
+.. method:: FieldFile.delete(save=True)
+
+Deletes the file associated with this instance and clears all attributes on 
+the field. Note: This method will close the file if it happens to be open when 
+``delete()`` is called.
+
+The optional ``save`` argument controls whether or not the instance is saved 
+after the file has been deleted. Defaults to ``True``.
+
 ``FilePathField``
 -----------------
 
@@ -632 +673 @@
 
 .. class:: ImageField(upload_to=None, [height_field=None, width_field=None, max_length=100, **options])
 
-Like :class:`FileField`, but validates that the uploaded object is a valid
-image. Has two extra optional arguments:
+Inherits all attributes and methods from :class:`FileField`, but validates 
+that the uploaded object is a valid image.
 
+In addition to the special attributes that are available for :class:`FileField`,
+an :class:`ImageField` also has :attr:`~django.core.files.File.height` and
+:attr:`~django.core.files.File.width` attributes.
+
+To facilitate querying on those attributes, :class:`ImageField` has two extra 
+optional arguments:
+
 .. attribute:: ImageField.height_field
 
     Name of a model field which will be auto-populated with the height of the
@@ -645 +693 @@
     Name of a model field which will be auto-populated with the width of the
     image each time the model instance is saved.
 
-In addition to the special attributes that are available for :class:`FileField`,
-an :class:`ImageField` also has :attr:`~django.core.files.File.height` and
-:attr:`~django.core.files.File.width` attributes.
-
 Requires the `Python Imaging Library`_.
 
 .. _Python Imaging Library: http://www.pythonware.com/products/pil/
@@ -656 +700 @@
 .. versionadded:: 1.0
    The ``max_length`` argument was added in this version.
 
-By default, :class:`ImageField` instances are
-created as ``varchar(100)`` columns in your database. As with other fields, you
-can change the maximum length using the :attr:`~CharField.max_length` argument.
+By default, :class:`ImageField` instances are created as ``varchar(100)`` 
+columns in your database. As with other fields, you can change the maximum 
+length using the :attr:`~CharField.max_length` argument.
 
 ``IntegerField``
 ----------------