A bunch of cleanups to file documentation. Along the way some references to the old file methods were removed - thanks, varikin.
Fixes #8642. git-svn-id: http://code.djangoproject.com/svn/django/trunk@8862 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jacob Kaplan-Moss
parent
c1de41f4d2
commit
bc768e2b47
|
|
@ -45,21 +45,24 @@ Django database layer.
|
|||
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 }}``.
|
||||
|
|
|
|||
|
|
@ -12,109 +12,110 @@ The ``File`` object
|
|||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -415,20 +415,20 @@ A file-upload field. Has one **required** argument:
|
|||
.. 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 @@ takes a few steps:
|
|||
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 @@ day. If you upload a file on Jan. 15, 2007, it will be saved in the directory
|
|||
``/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 @@ image. Has two extra optional arguments:
|
|||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue