Ticket #8642: r8695.diff

File r8695.diff, 8.3 KB (added by varikin, 7 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:`FileField` or an :class:`ImageField` in a model takes a few steps:
    4949
    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.
     50    #. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the
     51       full path to a directory where you'd like Django to store uploaded files.
     52       (For performance, these files are not stored in the database.) Define
     53       :setting:`MEDIA_URL` as the base public URL of that directory. Make sure
     54       that this directory is writable by the Web server's user account.
    5555
    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.
     56    #. Add the :class:`FileField` or :class:`ImageField` to your model, making
     57       sure to define the :attr:`~FileField.upload_to` option to tell Django to
     58       which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
    5959
    6060    #. 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 }}``.
     61       (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
     62       convenience :attr:`File.url` function provided by Django. For
     63       example, if your :class:`ImageField` is called ``mug_shot``, you can get
     64       the absolute URL to your image in a template with
     65       ``{{ 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.path
    1716
    1817The absolute path to the file's location on a local filesystem.
    1918
    2019:ref:`Custom file storage systems <howto-custom-file-storage>` may not store
    2120files locally; files stored on these systems will have a ``path`` of ``None``.
    2221
    23 ``File.url``
    24 ~~~~~~~~~~~~
     22.. attribute:: File.url
    2523
    2624The URL where the file can be retrieved. This is often useful in :ref:`templates
    2725<topics-templates>`; for example, a bit of a template for displaying a ``Car``
     
    2927
    3028    <img src='{{ car.photo.url }}' alt='{{ car.name }}' />
    3129
    32 ``File.size``
    33 ~~~~~~~~~~~~~
     30.. attribute:: File.size
    3431
    3532The size of the file in bytes.
    3633
    37 ``File.open(mode=None)``
    38 ~~~~~~~~~~~~~~~~~~~~~~~~
     34.. method:: File.open(mode=None)
    3935
    4036Open or reopen the file (which by definition also does ``File.seek(0)``). The
    4137``mode`` argument allows the same values as Python's standard ``open()``.
     
    4339When reopening a file, ``mode`` will override whatever mode the file was
    4440originally opened with; ``None`` means to reopen with the original mode.
    4541
    46 ``File.read(num_bytes=None)``
    47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     42.. method:: File.read(num_bytes=None)
    4843
    4944Read content from the file. The optional ``size`` is the number of bytes to
    5045read; if not specified, the file will be read to the end.
    5146
    52 ``File.__iter__()``
    53 ~~~~~~~~~~~~~~~~~~~
     47.. method:: File.__iter__()
    5448
    5549Iterate over the file yielding one line at a time.
    5650
    57 ``File.chunks(chunk_size=None)``
    58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     51.. method:: File.chunks(chunk_size=None)
    5952
    6053Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults
    6154to 64 KB.
     
    6356This is especially useful with very large files since it allows them to be
    6457streamed off disk and avoids storing the whole file in memory.
    6558
    66 ``File.multiple_chunks(chunk_size=None)``
    67 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     59.. method:: File.multiple_chunks(chunk_size=None)
    6860
    6961Returns ``True`` if the file is large enough to require multiple chunks to
    7062access all of its content give some ``chunk_size``.
    7163
    72 ``File.write(content)``
    73 ~~~~~~~~~~~~~~~~~~~~~~~
     64.. method:: File.write(content)
    7465
    7566Writes the specified content string to the file. Depending on the storage system
    7667behind the scenes, this content might not be fully committed until ``close()``
    7768is called on the file.
    7869
    79 ``File.close()``
    80 ~~~~~~~~~~~~~~~~
     70.. method:: File.close()
    8171
    8272Close the file.
    8373
    8474Additional ``ImageField`` attributes
    8575------------------------------------
    8676
    87 ``File.width`` and ``File.height``
    88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     77.. attribute:: File.width
     78.. attribute:: File.height
    8979
    9080These attributes provide the dimensions of the image.
    9181
    9282Additional methods on files attached to objects
    9383-----------------------------------------------
    9484
    95 Any ``File`` that's associated with an object (as with ``Car.photo``, above)
     85Any :class:`File` that's associated with an object (as with ``Car.photo``, above)
    9686will also have a couple of extra methods:
    9787
    98 ``File.save(name, content, save=True)``
    99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     88.. method:: File.save(name, content, save=True)
    10089
    10190Saves a new file with the file name and contents provided. This will not replace
    10291the 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
     92it. ``save`` is ``True``, the model's ``save()`` method will be called once
    10493the file is saved. That is, these two lines::
    10594
    10695    >>> car.photo.save('myphoto.jpg', contents, save=False)
     
    11099
    111100    >>> car.photo.save('myphoto.jpg', contents, save=True)
    112101
    113 ``File.delete(save=True)``
    114 ~~~~~~~~~~~~~~~~~~~~~~~~~~
     102.. method:: File.delete(save=True)
    115103
    116104Remove the file from the model instance and delete the underlying file. The
    117105``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:`File.url` attribute.
    420419
    421420    This path may contain `strftime formatting`_, which will be replaced by the
    422421    date/time of the file upload (so that uploaded files don't fill up the given
     
    475474
    476475    3. All that will be stored in your database is a path to the file
    477476       (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
    478        convenience ``get_<fieldname>_url`` function provided by Django. For
     477       convenience :attr:`File.url` function provided by Django. For
    479478       example, if your :class:`ImageField` is called ``mug_shot``, you can get
    480479       the absolute URL to your image in a template with ``{{
    481        object.get_mug_shot_url }}``.
     480       object.mug_shot.url }}``.
    482481
    483482For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and
    484483:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'``
     
    488487``/home/media/photos/2007/01/15``.
    489488
    490489If 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`.
     490to that file, or the file's size, you can use the :attr:`File.name`, :attr:`File.url`
     491and :attr:`File.size` attributes; see :ref:`topics-files`.
    493492
    494493Note that whenever you deal with uploaded files, you should pay close attention
    495494to where you're uploading them and what type of files they are, to avoid
Back to Top