Author: jacob
Date: 2008-09-02 12:33:51 -0500 (Tue, 02 Sep 2008)
New Revision: 8862
Modified:
django/trunk/docs/faq/usage.txt
django/trunk/docs/ref/files/file.txt
django/trunk/docs/ref/models/fields.txt
Log:
A bunch of cleanups to file documentation. Along the way some references to the
old file methods were removed - thanks, varikin.
Fixes #8642.
Modified: django/trunk/docs/faq/usage.txt
===================================================================
--- django/trunk/docs/faq/usage.txt 2008-09-02 17:26:24 UTC (rev 8861)
+++ django/trunk/docs/faq/usage.txt 2008-09-02 17:33:51 UTC (rev 8862)
@@ -45,21 +45,24 @@
How do I use image and file fields?
-----------------------------------
-Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:
+Using a :class:`~django.db.models.FileField` or an
+:class:`~django.db.models.ImageField` in a model takes a few steps:
- #. In your settings file, define ``MEDIA_ROOT`` as the full path to
- a directory where you'd like Django to store uploaded files. (For
- performance, these files are not stored in the database.) Define
- ``MEDIA_URL`` as the base public URL of that directory. Make sure that
- this directory is writable by the Web server's user account.
+ #. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as
the
+ full path to a directory where you'd like Django to store uploaded
files.
+ (For performance, these files are not stored in the database.) Define
+ :setting:`MEDIA_URL` as the base public URL of that directory. Make sure
+ that this directory is writable by the Web server's user account.
- #. Add the ``FileField`` or ``ImageField`` to your model, making sure
- to define the ``upload_to`` option to tell Django to which subdirectory
- of ``MEDIA_ROOT`` it should upload files.
+ #. Add the :class:`~django.db.models.FileField` or
+ :class:`~django.db.models.ImageField` to your model, making sure to
+ define the :attr:`~django.db.models.FileField.upload_to` option to tell
+ Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload
+ files.
- #. All that will be stored in your database is a path to the file
- (relative to ``MEDIA_ROOT``). You'll most likely want to use the
- convenience ``get_<fieldname>_url`` function provided by Django. For
- example, if your ``ImageField`` is called ``mug_shot``, you can get the
- absolute URL to your image in a template with
- ``{{ object.get_mug_shot_url }}``.
+ #. All that will be stored in your database is a path to the file
+ (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
+ convenience :attr:`~django.core.files.File.url` attribute provided by
+ Django. For example, if your :class:`~django.db.models.ImageField` is
+ called ``mug_shot``, you can get the absolute URL to your image in a
+ template with ``{{ object.mug_shot.url }}``.
Modified: django/trunk/docs/ref/files/file.txt
===================================================================
--- django/trunk/docs/ref/files/file.txt 2008-09-02 17:26:24 UTC (rev
8861)
+++ django/trunk/docs/ref/files/file.txt 2008-09-02 17:33:51 UTC (rev
8862)
@@ -12,109 +12,110 @@
Django's ``File`` has the following attributes and methods:
-``File.path``
-~~~~~~~~~~~~~
+.. attribute:: File.name
-The absolute path to the file's location on a local filesystem.
+ The name of file including the relative path from :setting:`MEDIA_ROOT`.
-:ref:`Custom file storage systems <howto-custom-file-storage>` may not store
-files locally; files stored on these systems will have a ``path`` of ``None``.
+.. attribute:: File.path
-``File.url``
-~~~~~~~~~~~~
+ The absolute path to the file's location on a local filesystem.
-The URL where the file can be retrieved. This is often useful in
:ref:`templates
-<topics-templates>`; for example, a bit of a template for displaying a ``Car``
-(see above) might look like::
+ :ref:`Custom file storage systems <howto-custom-file-storage>` may not
store
+ files locally; files stored on these systems will have a ``path`` of
+ ``None``.
- <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
+.. attribute:: File.url
-``File.size``
-~~~~~~~~~~~~~
+ The URL where the file can be retrieved. This is often useful in
+ :ref:`templates <topics-templates>`; for example, a bit of a template for
+ displaying a ``Car`` (see above) might look like:
+
+ .. code-block:: html+django
-The size of the file in bytes.
+ <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
-``File.open(mode=None)``
-~~~~~~~~~~~~~~~~~~~~~~~~
+.. attribute:: File.size
-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()``.
+ The size of the file in bytes.
-When reopening a file, ``mode`` will override whatever mode the file was
-originally opened with; ``None`` means to reopen with the original mode.
+.. method:: File.open(mode=None)
-``File.read(num_bytes=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()``.
-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.
+ When reopening a file, ``mode`` will override whatever mode the file was
+ originally opened with; ``None`` means to reopen with the original mode.
-``File.__iter__()``
-~~~~~~~~~~~~~~~~~~~
+.. method:: File.read(num_bytes=None)
-Iterate over the file yielding one line at a time.
+ 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.
-``File.chunks(chunk_size=None)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. method:: File.__iter__()
-Iterate over the file yielding "chunks" of a given size. ``chunk_size``
defaults
-to 64 KB.
+ Iterate over the file yielding one line at a time.
-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:: File.chunks(chunk_size=None)
-``File.multiple_chunks(chunk_size=None)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Iterate over the file yielding "chunks" of a given size. ``chunk_size``
+ defaults to 64 KB.
-Returns ``True`` if the file is large enough to require multiple chunks to
-access all of its content give some ``chunk_size``.
+ 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.
-``File.write(content)``
-~~~~~~~~~~~~~~~~~~~~~~~
+.. method:: File.multiple_chunks(chunk_size=None)
-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.
+ Returns ``True`` if the file is large enough to require multiple chunks to
+ access all of its content give some ``chunk_size``.
-``File.close()``
-~~~~~~~~~~~~~~~~
+.. method:: File.write(content)
-Close 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:: File.close()
+
+ Close the file.
+
Additional ``ImageField`` attributes
------------------------------------
-``File.width`` and ``File.height``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. attribute:: File.width
+
+ Width of the image.
-These attributes provide the dimensions of the image.
+.. attribute:: File.height
+ Heigght of the image.
+
Additional methods on files attached to objects
-----------------------------------------------
-Any ``File`` that's associated with an object (as with ``Car.photo``, above)
-will also have a couple of extra methods:
+.. highlight:: pycon
-``File.save(name, content, save=True)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Any :class:`File` that's associated with an object (as with ``Car.photo``,
+above) will also have a couple of extra methods:
-Saves a new file with the file name and contents provided. This will not
replace
-the existing file, but will create a new file and update the object to point to
-it. If ``save`` is ``True``, the model's ``save()`` method will be called once
-the file is saved. That is, these two lines::
+.. method:: File.save(name, content, save=True)
- >>> car.photo.save('myphoto.jpg', contents, save=False)
- >>> car.save()
+ Saves a new file with the file name and contents provided. This will not
+ replace the existing file, but will create a new file and update the object
+ to point to it. If ``save`` is ``True``, the model's ``save()`` method will
+ be called once the file is saved. That is, these two lines::
+
+ >>> car.photo.save('myphoto.jpg', contents, save=False)
+ >>> car.save()
+
+ are the same as this one line::
+
+ >>> 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`.
-are the same as this one line::
+.. method:: File.delete(save=True)
- >>> 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`.
-
-``File.delete(save=True)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Remove the file from the model instance and delete the underlying file. The
-``save`` argument works as above.
+ Remove the file from the model instance and delete the underlying file. The
+ ``save`` argument works as above.
Modified: django/trunk/docs/ref/models/fields.txt
===================================================================
--- django/trunk/docs/ref/models/fields.txt 2008-09-02 17:26:24 UTC (rev
8861)
+++ django/trunk/docs/ref/models/fields.txt 2008-09-02 17:33:51 UTC (rev
8862)
@@ -415,20 +415,20 @@
.. attribute:: FileField.upload_to
A local filesystem path that will be appended to your :setting:`MEDIA_ROOT`
- setting to determine the output of the ``get_<fieldname>_url()`` helper
- function.
+ setting to determine the value of the :attr:`~django.core.files.File.url`
+ attribute.
This path may contain `strftime formatting`_, which will be replaced by the
date/time of the file upload (so that uploaded files don't fill up the
given
directory).
- .. versionadded:: 1.0
+ .. versionchanged:: 1.0
This may also be a callable, such as a function, which will be called to
- obtain the upload path, including the filename. This callable must be
- able to accept two arguments, and return a Unix-style path (with forward
- slashes) to be passed along to the storage system. The two arguments that
will
- be passed are:
+ obtain the upload path, including the filename. This callable must be able
+ to accept two arguments, and return a Unix-style path (with forward
slashes)
+ to be passed along to the storage system. The two arguments that will be
+ passed are:
====================== ===============================================
Argument Description
@@ -470,15 +470,15 @@
that this directory is writable by the Web server's user account.
2. Add the :class:`FileField` or :class:`ImageField` to your model, making
- sure to define the :attr:`~FileField.upload_to` option to tell Django to
- which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
+ sure to define the :attr:`~FileField.upload_to` option to tell Django
+ to which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
3. All that will be stored in your database is a path to the file
(relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
- convenience ``get_<fieldname>_url`` function provided by Django. For
- example, if your :class:`ImageField` is called ``mug_shot``, you can get
- the absolute URL to your image in a template with ``{{
- object.get_mug_shot_url }}``.
+ convenience :attr:`~django.core.files.File.url` function provided by
+ Django. For example, if your :class:`ImageField` is called
``mug_shot``,
+ you can get the absolute URL to your image in a template with
+ ``{{ object.mug_shot.url }}``.
For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and
:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The
``'%Y/%m/%d'``
@@ -488,8 +488,9 @@
``/home/media/photos/2007/01/15``.
If you want to retrieve the upload file's on-disk filename, or a URL that
refers
-to that file, or the file's size, you can use the ``File.name``, ``File.url``
-and ``File.size`` attributes; see :ref:`topics-files`.
+to that file, or the file's size, you can use the
+:attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url`
+and :attr:`~django.core.files.File.size` attributes; see :ref:`topics-files`.
Note that whenever you deal with uploaded files, you should pay close attention
to where you're uploading them and what type of files they are, to avoid
@@ -581,7 +582,7 @@
Name of a model field which will be auto-populated with the height of the
image each time the model instance is saved.
-.. attribute:: ImageField.width_field`
+.. attribute:: ImageField.width_field
Name of a model field which will be auto-populated with the width of the
image each time the model instance is saved.
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
