Permalink
Browse files

[1.1.X] Fixed #12229 -- Added documentation of the FieldFile methods …

…that are exposed by FileField and ImageField. Thanks to Gabriel Hurley for the draft patch.

Backport of r13202 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@13203 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
freakboy3742 committed May 10, 2010
1 parent 0765d4b commit 6bc070ba4cc687bea93fab5b9122063c9d51d1e6
Showing with 54 additions and 12 deletions.
  1. +54 −12 docs/ref/models/fields.txt
@@ -545,6 +545,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``
-----------------
@@ -605,8 +644,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
@@ -618,20 +664,16 @@ 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 ``File.height`` and ``File.width`` attributes.
See :ref:`topics-files`.
Requires the `Python Imaging Library`_.
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
.. 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``
----------------
@@ -844,9 +886,9 @@ define the details of how the relation works.
current date/time to be chosen.
Instead of a dictionary this can also be a :class:`~django.db.models.Q`
object for more :ref:`complex queries <complex-lookups-with-q>`. However,
if ``limit_choices_to`` is a :class:`~django.db.models.Q` object then it
will only have an effect on the choices available in the admin when the
object for more :ref:`complex queries <complex-lookups-with-q>`. However,
if ``limit_choices_to`` is a :class:`~django.db.models.Q` object then it
will only have an effect on the choices available in the admin when the
field is not listed in ``raw_id_fields`` in the ``ModelAdmin`` for the model.
.. attribute:: ForeignKey.related_name

0 comments on commit 6bc070b

Please sign in to comment.