Commit bc768e2b authored by Jacob Kaplan-Moss's avatar Jacob Kaplan-Moss
Browse files

A bunch of cleanups to file documentation. Along the way some references to... 

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
parent c1de41f4

docs/faq/usage.txt

+21 −18
Original line number Diff line number Diff line
@@ -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 }}``.
 
       (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 }}``.

docs/ref/files/file.txt

+70 −69
Original line number Diff line number Diff line
@@ -12,96 +12,98 @@ The ``File`` object 


Django's ``File`` has the following attributes and methods:



``File.path``

~~~~~~~~~~~~~

.. attribute:: File.name



    The name of file including the relative path from :setting:`MEDIA_ROOT`.



.. attribute:: File.path



    The absolute path to the file's location on a local filesystem.



    :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``.

    files locally; files stored on these systems will have a ``path`` of

    ``None``.



.. attribute:: File.url



``File.url``

~~~~~~~~~~~~

    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:

    

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



        <img src='{{ car.photo.url }}' alt='{{ car.name }}' />



``File.size``

~~~~~~~~~~~~~

.. attribute:: File.size



    The size of the file in bytes.



``File.open(mode=None)``

~~~~~~~~~~~~~~~~~~~~~~~~

.. method:: File.open(mode=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()``.

    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()``.



    When reopening a file, ``mode`` will override whatever mode the file was

    originally opened with; ``None`` means to reopen with the original mode.



``File.read(num_bytes=None)``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. method:: File.read(num_bytes=None)



    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.__iter__()``

~~~~~~~~~~~~~~~~~~~

.. method:: File.__iter__()



    Iterate over the file yielding one line at a time.



``File.chunks(chunk_size=None)``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. method:: File.chunks(chunk_size=None)



Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults

to 64 KB.

    Iterate over the file yielding "chunks" of a given size. ``chunk_size``

    defaults to 64 KB.



    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.multiple_chunks(chunk_size=None)``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. method:: File.multiple_chunks(chunk_size=None)



    Returns ``True`` if the file is large enough to require multiple chunks to

    access all of its content give some ``chunk_size``.



``File.write(content)``

~~~~~~~~~~~~~~~~~~~~~~~

.. method:: File.write(content)



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.

    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.



``File.close()``

~~~~~~~~~~~~~~~~

.. method:: File.close()



    Close the file.



Additional ``ImageField`` attributes

------------------------------------



``File.width`` and ``File.height``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. attribute:: File.width

    

These attributes provide the dimensions of the image.

    Width 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



Any :class:`File` that's associated with an object (as with ``Car.photo``,

above) will also have a couple of extra methods:



``File.save(name, content, save=True)``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. method:: File.save(name, content, save=True)



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::

    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()
@@ -113,8 +115,7 @@ are the same as this one line:: 
    Note that the ``content`` argument must be an instance of

    :class:`File` or of a subclass of :class:`File`.



``File.delete(save=True)``

~~~~~~~~~~~~~~~~~~~~~~~~~~

.. method:: File.delete(save=True)



    Remove the file from the model instance and delete the underlying file. The

    ``save`` argument works as above.

docs/ref/models/fields.txt

+17 −16
Original line number Diff line number Diff line
@@ -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.