Ticket #8642: r8695.diff
| File r8695.diff, 8.3 KB (added by , 16 years ago) |
|---|
-
docs/faq/usage.txt
45 45 How do I use image and file fields? 46 46 ----------------------------------- 47 47 48 Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:48 Using a :class:`FileField` or an :class:`ImageField` in a model takes a few steps: 49 49 50 #. In your settings file, define ``MEDIA_ROOT`` as the full path to51 a directory where you'd like Django to store uploaded files. (For52 performance, these files are not stored in the database.) Define53 ``MEDIA_URL`` as the base public URL of that directory. Make sure that54 th is 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. 55 55 56 #. Add the ``FileField`` or ``ImageField`` to your model, making sure57 to define the ``upload_to`` option to tell Django to which subdirectory58 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. 59 59 60 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 the62 convenience ``get_<fieldname>_url`` function provided by Django. For63 example, if your ``ImageField`` is called ``mug_shot``, you can get the64 absolute URL to your image in a template with65 ``{{ 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
12 12 13 13 Django's ``File`` has the following attributes and methods: 14 14 15 ``File.path`` 16 ~~~~~~~~~~~~~ 15 .. attribute:: File.path 17 16 18 17 The absolute path to the file's location on a local filesystem. 19 18 20 19 :ref:`Custom file storage systems <howto-custom-file-storage>` may not store 21 20 files locally; files stored on these systems will have a ``path`` of ``None``. 22 21 23 ``File.url`` 24 ~~~~~~~~~~~~ 22 .. attribute:: File.url 25 23 26 24 The URL where the file can be retrieved. This is often useful in :ref:`templates 27 25 <topics-templates>`; for example, a bit of a template for displaying a ``Car`` … … 29 27 30 28 <img src='{{ car.photo.url }}' alt='{{ car.name }}' /> 31 29 32 ``File.size`` 33 ~~~~~~~~~~~~~ 30 .. attribute:: File.size 34 31 35 32 The size of the file in bytes. 36 33 37 ``File.open(mode=None)`` 38 ~~~~~~~~~~~~~~~~~~~~~~~~ 34 .. method:: File.open(mode=None) 39 35 40 36 Open or reopen the file (which by definition also does ``File.seek(0)``). The 41 37 ``mode`` argument allows the same values as Python's standard ``open()``. … … 43 39 When reopening a file, ``mode`` will override whatever mode the file was 44 40 originally opened with; ``None`` means to reopen with the original mode. 45 41 46 ``File.read(num_bytes=None)`` 47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 42 .. method:: File.read(num_bytes=None) 48 43 49 44 Read content from the file. The optional ``size`` is the number of bytes to 50 45 read; if not specified, the file will be read to the end. 51 46 52 ``File.__iter__()`` 53 ~~~~~~~~~~~~~~~~~~~ 47 .. method:: File.__iter__() 54 48 55 49 Iterate over the file yielding one line at a time. 56 50 57 ``File.chunks(chunk_size=None)`` 58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 51 .. method:: File.chunks(chunk_size=None) 59 52 60 53 Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults 61 54 to 64 KB. … … 63 56 This is especially useful with very large files since it allows them to be 64 57 streamed off disk and avoids storing the whole file in memory. 65 58 66 ``File.multiple_chunks(chunk_size=None)`` 67 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 59 .. method:: File.multiple_chunks(chunk_size=None) 68 60 69 61 Returns ``True`` if the file is large enough to require multiple chunks to 70 62 access all of its content give some ``chunk_size``. 71 63 72 ``File.write(content)`` 73 ~~~~~~~~~~~~~~~~~~~~~~~ 64 .. method:: File.write(content) 74 65 75 66 Writes the specified content string to the file. Depending on the storage system 76 67 behind the scenes, this content might not be fully committed until ``close()`` 77 68 is called on the file. 78 69 79 ``File.close()`` 80 ~~~~~~~~~~~~~~~~ 70 .. method:: File.close() 81 71 82 72 Close the file. 83 73 84 74 Additional ``ImageField`` attributes 85 75 ------------------------------------ 86 76 87 ``File.width`` and ``File.height`` 88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 77 .. attribute:: File.width 78 .. attribute:: File.height 89 79 90 80 These attributes provide the dimensions of the image. 91 81 92 82 Additional methods on files attached to objects 93 83 ----------------------------------------------- 94 84 95 Any ``File`` that's associated with an object (as with ``Car.photo``, above)85 Any :class:`File` that's associated with an object (as with ``Car.photo``, above) 96 86 will also have a couple of extra methods: 97 87 98 ``File.save(name, content, save=True)`` 99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 88 .. method:: File.save(name, content, save=True) 100 89 101 90 Saves a new file with the file name and contents provided. This will not replace 102 91 the 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 once92 it. ``save`` is ``True``, the model's ``save()`` method will be called once 104 93 the file is saved. That is, these two lines:: 105 94 106 95 >>> car.photo.save('myphoto.jpg', contents, save=False) … … 110 99 111 100 >>> car.photo.save('myphoto.jpg', contents, save=True) 112 101 113 ``File.delete(save=True)`` 114 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 102 .. method:: File.delete(save=True) 115 103 116 104 Remove the file from the model instance and delete the underlying file. The 117 105 ``save`` argument works as above. -
docs/ref/models/fields.txt
415 415 .. attribute:: FileField.upload_to 416 416 417 417 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. 420 419 421 420 This path may contain `strftime formatting`_, which will be replaced by the 422 421 date/time of the file upload (so that uploaded files don't fill up the given … … 475 474 476 475 3. All that will be stored in your database is a path to the file 477 476 (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the 478 convenience ``get_<fieldname>_url`` function provided by Django. For477 convenience :attr:`File.url` function provided by Django. For 479 478 example, if your :class:`ImageField` is called ``mug_shot``, you can get 480 479 the absolute URL to your image in a template with ``{{ 481 object. get_mug_shot_url }}``.480 object.mug_shot.url }}``. 482 481 483 482 For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and 484 483 :attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` … … 488 487 ``/home/media/photos/2007/01/15``. 489 488 490 489 If 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`.490 to that file, or the file's size, you can use the :attr:`File.name`, :attr:`File.url` 491 and :attr:`File.size` attributes; see :ref:`topics-files`. 493 492 494 493 Note that whenever you deal with uploaded files, you should pay close attention 495 494 to where you're uploading them and what type of files they are, to avoid