Ticket #8642: r8695.2.diff

File r8695.2.diff, 10.0 KB (added by John Shimek, 16 years ago)
  • docs/faq/usage.txt

     
    4545How do I use image and file fields?
    4646-----------------------------------
    4747
    48 Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:
     48Using a :class:`~django.db.models.FileField` or an
     49:class:`~django.db.models.ImageField` in a model takes a few steps:
    4950
    50     #. In your settings file, define ``MEDIA_ROOT`` as the full path to
    51        a directory where you'd like Django to store uploaded files. (For
    52        performance, these files are not stored in the database.) Define
    53        ``MEDIA_URL`` as the base public URL of that directory. Make sure that
    54        this directory is writable by the Web server's user account.
     51    #. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the
     52       full path to a directory where you'd like Django to store uploaded files.
     53       (For performance, these files are not stored in the database.) Define
     54       :setting:`MEDIA_URL` as the base public URL of that directory. Make sure
     55       that this directory is writable by the Web server's user account.
    5556
    56     #. Add the ``FileField`` or ``ImageField`` to your model, making sure
    57        to define the ``upload_to`` option to tell Django to which subdirectory
    58        of ``MEDIA_ROOT`` it should upload files.
     57    #. Add the :class:`~django.db.models.FileField` or
     58       :class:`~django.db.models.ImageField` to your model, making sure to
     59       define the :attr:`~django.db.models.FileField.upload_to` option to tell
     60       Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload
     61       files.
    5962
    60     #. All that will be stored in your database is a path to the file
    61        (relative to ``MEDIA_ROOT``). You'll most likely want to use the
    62        convenience ``get_<fieldname>_url`` function provided by Django. For
    63        example, if your ``ImageField`` is called ``mug_shot``, you can get the
    64        absolute URL to your image in a template with
    65        ``{{ object.get_mug_shot_url }}``.
     63    #. All that will be stored in your database is a path to the file 
     64       (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
     65       convenience :attr:`~django.core.files.File.url` attribute provided by
     66       Django. For example, if your :class:`~django.db.models.ImageField` is
     67       called ``mug_shot``, you can get the absolute URL to your image in a
     68       template with ``{{ object.mug_shot.url }}``.
  • docs/ref/files/file.txt

     
    1212
    1313Django's ``File`` has the following attributes and methods:
    1414
    15 ``File.path``
    16 ~~~~~~~~~~~~~
     15.. attribute:: File.name
    1716
     17The name of file including the relative path from :setting:`MEDIA_ROOT`.
     18
     19.. attribute:: File.path
     20
    1821The absolute path to the file's location on a local filesystem.
    1922
    2023:ref:`Custom file storage systems <howto-custom-file-storage>` may not store
    2124files locally; files stored on these systems will have a ``path`` of ``None``.
    2225
    23 ``File.url``
    24 ~~~~~~~~~~~~
     26.. attribute:: File.url
    2527
    2628The URL where the file can be retrieved. This is often useful in :ref:`templates
    2729<topics-templates>`; for example, a bit of a template for displaying a ``Car``
     
    2931
    3032    <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
    3133
    32 ``File.size``
    33 ~~~~~~~~~~~~~
     34.. attribute:: File.size
    3435
    3536The size of the file in bytes.
    3637
    37 ``File.open(mode=None)``
    38 ~~~~~~~~~~~~~~~~~~~~~~~~
     38.. method:: File.open(mode=None)
    3939
    4040Open or reopen the file (which by definition also does ``File.seek(0)``). The
    4141``mode`` argument allows the same values as Python's standard ``open()``.
     
    4343When reopening a file, ``mode`` will override whatever mode the file was
    4444originally opened with; ``None`` means to reopen with the original mode.
    4545
    46 ``File.read(num_bytes=None)``
    47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     46.. method:: File.read(num_bytes=None)
    4847
    4948Read content from the file. The optional ``size`` is the number of bytes to
    5049read; if not specified, the file will be read to the end.
    5150
    52 ``File.__iter__()``
    53 ~~~~~~~~~~~~~~~~~~~
     51.. method:: File.__iter__()
    5452
    5553Iterate over the file yielding one line at a time.
    5654
    57 ``File.chunks(chunk_size=None)``
    58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     55.. method:: File.chunks(chunk_size=None)
    5956
    6057Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults
    6158to 64 KB.
     
    6360This is especially useful with very large files since it allows them to be
    6461streamed off disk and avoids storing the whole file in memory.
    6562
    66 ``File.multiple_chunks(chunk_size=None)``
    67 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     63.. method:: File.multiple_chunks(chunk_size=None)
    6864
    6965Returns ``True`` if the file is large enough to require multiple chunks to
    7066access all of its content give some ``chunk_size``.
    7167
    72 ``File.write(content)``
    73 ~~~~~~~~~~~~~~~~~~~~~~~
     68.. method:: File.write(content)
    7469
    7570Writes the specified content string to the file. Depending on the storage system
    7671behind the scenes, this content might not be fully committed until ``close()``
    7772is called on the file.
    7873
    79 ``File.close()``
    80 ~~~~~~~~~~~~~~~~
     74.. method:: File.close()
    8175
    8276Close the file.
    8377
    8478Additional ``ImageField`` attributes
    8579------------------------------------
    8680
    87 ``File.width`` and ``File.height``
    88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     81.. attribute:: File.width
     82.. attribute:: File.height
    8983
    9084These attributes provide the dimensions of the image.
    9185
    9286Additional methods on files attached to objects
    9387-----------------------------------------------
    9488
    95 Any ``File`` that's associated with an object (as with ``Car.photo``, above)
     89Any :class:`File` that's associated with an object (as with ``Car.photo``, above)
    9690will also have a couple of extra methods:
    9791
    98 ``File.save(name, content, save=True)``
    99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     92.. method:: File.save(name, content, save=True)
    10093
    10194Saves a new file with the file name and contents provided. This will not replace
    10295the existing file, but will create a new file and update the object to point to
    103 it. If ``save`` is ``True``, the model's ``save()`` method will be called once
     96it. ``save`` is ``True``, the model's ``save()`` method will be called once
    10497the file is saved. That is, these two lines::
    10598
    10699    >>> car.photo.save('myphoto.jpg', contents, save=False)
     
    110103
    111104    >>> car.photo.save('myphoto.jpg', contents, save=True)
    112105
    113 ``File.delete(save=True)``
    114 ~~~~~~~~~~~~~~~~~~~~~~~~~~
     106.. method:: File.delete(save=True)
    115107
    116108Remove the file from the model instance and delete the underlying file. The
    117109``save`` argument works as above.
  • docs/ref/models/fields.txt

     
    415415.. attribute:: FileField.upload_to
    416416   
    417417    A local filesystem path that will be appended to your :setting:`MEDIA_ROOT`
    418     setting to determine the output of the ``get_<fieldname>_url()`` helper
    419     function.
     418    setting to determine the value of the :attr:`~django.core.files.File.url`
     419    attribute.
    420420
    421421    This path may contain `strftime formatting`_, which will be replaced by the
    422422    date/time of the file upload (so that uploaded files don't fill up the given
     
    460460The admin represents this field as an ``<input type="file">`` (a file-upload
    461461widget).
    462462
    463 Using a :class:`FileField` or an :class:`ImageField` (see below) in a model
     463Using a :class:`FileField` or an :class:`ImageField` (see below) in a model 
    464464takes a few steps:
    465465
    466466    1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the
     
    470470       that this directory is writable by the Web server's user account.
    471471
    472472    2. Add the :class:`FileField` or :class:`ImageField` to your model, making
    473        sure to define the :attr:`~FileField.upload_to` option to tell Django to
    474        which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
     473       sure to define the :attr:`~FileField.upload_to` option to tell Django
     474       to which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
    475475
    476476    3. All that will be stored in your database is a path to the file
    477477       (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
    478        convenience ``get_<fieldname>_url`` function provided by Django. For
    479        example, if your :class:`ImageField` is called ``mug_shot``, you can get
    480        the absolute URL to your image in a template with ``{{
    481        object.get_mug_shot_url }}``.
     478       convenience :attr:`~django.core.files.File.url` function provided by
     479       Django. For example, if your :class:`ImageField` is called ``mug_shot``,
     480       you can get the absolute URL to your image in a template with
     481       ``{{ object.mug_shot.url }}``.
    482482
    483483For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and
    484484:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'``
     
    488488``/home/media/photos/2007/01/15``.
    489489
    490490If you want to retrieve the upload file's on-disk filename, or a URL that refers
    491 to that file, or the file's size, you can use the ``File.name``, ``File.url``
    492 and ``File.size`` attributes; see :ref:`topics-files`.
     491to that file, or the file's size, you can use the
     492:attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url`
     493and :attr:`~django.core.files.File.size` attributes; see :ref:`topics-files`.
    493494
    494495Note that whenever you deal with uploaded files, you should pay close attention
    495496to where you're uploading them and what type of files they are, to avoid
     
    575576    Name of a model field which will be auto-populated with the height of the
    576577    image each time the model instance is saved.
    577578
    578 .. attribute:: ImageField.width_field`
     579.. attribute:: ImageField.width_field
    579580
    580581    Name of a model field which will be auto-populated with the width of the
    581582    image each time the model instance is saved.
Back to Top