Fixed #12229 -- Added documentation of the FieldFile methods that are exposed by FileField and ImageField. Thanks to Gabriel Hurley for the draft patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13202 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Russell Keith-Magee 2010-05-10 12:29:04 +00:00
parent 34587d8a2a
commit 819f43f499
1 changed files with 54 additions and 12 deletions

View File

@ -572,6 +572,45 @@ can change the maximum length using the :attr:`~CharField.max_length` argument.
.. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime
FileField and FieldFile
~~~~~~~~~~~~~~~~~~~~~~~
When you access a :class:`FileField` on a model, you are given an instance
of :class:`FieldFile` as a proxy for accessing the underlying file. This
class has several methods that can be used to interact with file data:
.. 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 the field, then associates the stored file with the model field.
If you want to manually associate file data with :class:`FileField`
instances on your model, the ``save()`` method is used to persist that file
data.
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,8 +671,15 @@ The admin represents this as an ``<input type="text">`` (a single-line input).
.. 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 also
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
@ -645,10 +691,6 @@ image. Has two extra optional arguments:
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,9 +698,9 @@ Requires the `Python Imaging Library`_.
.. 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``
----------------