Ticket #8642: r8695.2.diff
| File r8695.2.diff, 10.0 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:`~django.db.models.FileField` or an 49 :class:`~django.db.models.ImageField` in a model takes a few steps: 49 50 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.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. 55 56 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. 59 62 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 }}``.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
12 12 13 13 Django's ``File`` has the following attributes and methods: 14 14 15 ``File.path`` 16 ~~~~~~~~~~~~~ 15 .. attribute:: File.name 17 16 17 The name of file including the relative path from :setting:`MEDIA_ROOT`. 18 19 .. attribute:: File.path 20 18 21 The absolute path to the file's location on a local filesystem. 19 22 20 23 :ref:`Custom file storage systems <howto-custom-file-storage>` may not store 21 24 files locally; files stored on these systems will have a ``path`` of ``None``. 22 25 23 ``File.url`` 24 ~~~~~~~~~~~~ 26 .. attribute:: File.url 25 27 26 28 The URL where the file can be retrieved. This is often useful in :ref:`templates 27 29 <topics-templates>`; for example, a bit of a template for displaying a ``Car`` … … 29 31 30 32 <img src='{{ car.photo.url }}' alt='{{ car.name }}' /> 31 33 32 ``File.size`` 33 ~~~~~~~~~~~~~ 34 .. attribute:: File.size 34 35 35 36 The size of the file in bytes. 36 37 37 ``File.open(mode=None)`` 38 ~~~~~~~~~~~~~~~~~~~~~~~~ 38 .. method:: File.open(mode=None) 39 39 40 40 Open or reopen the file (which by definition also does ``File.seek(0)``). The 41 41 ``mode`` argument allows the same values as Python's standard ``open()``. … … 43 43 When reopening a file, ``mode`` will override whatever mode the file was 44 44 originally opened with; ``None`` means to reopen with the original mode. 45 45 46 ``File.read(num_bytes=None)`` 47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 .. method:: File.read(num_bytes=None) 48 47 49 48 Read content from the file. The optional ``size`` is the number of bytes to 50 49 read; if not specified, the file will be read to the end. 51 50 52 ``File.__iter__()`` 53 ~~~~~~~~~~~~~~~~~~~ 51 .. method:: File.__iter__() 54 52 55 53 Iterate over the file yielding one line at a time. 56 54 57 ``File.chunks(chunk_size=None)`` 58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 55 .. method:: File.chunks(chunk_size=None) 59 56 60 57 Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults 61 58 to 64 KB. … … 63 60 This is especially useful with very large files since it allows them to be 64 61 streamed off disk and avoids storing the whole file in memory. 65 62 66 ``File.multiple_chunks(chunk_size=None)`` 67 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 63 .. method:: File.multiple_chunks(chunk_size=None) 68 64 69 65 Returns ``True`` if the file is large enough to require multiple chunks to 70 66 access all of its content give some ``chunk_size``. 71 67 72 ``File.write(content)`` 73 ~~~~~~~~~~~~~~~~~~~~~~~ 68 .. method:: File.write(content) 74 69 75 70 Writes the specified content string to the file. Depending on the storage system 76 71 behind the scenes, this content might not be fully committed until ``close()`` 77 72 is called on the file. 78 73 79 ``File.close()`` 80 ~~~~~~~~~~~~~~~~ 74 .. method:: File.close() 81 75 82 76 Close the file. 83 77 84 78 Additional ``ImageField`` attributes 85 79 ------------------------------------ 86 80 87 ``File.width`` and ``File.height`` 88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 81 .. attribute:: File.width 82 .. attribute:: File.height 89 83 90 84 These attributes provide the dimensions of the image. 91 85 92 86 Additional methods on files attached to objects 93 87 ----------------------------------------------- 94 88 95 Any ``File`` that's associated with an object (as with ``Car.photo``, above)89 Any :class:`File` that's associated with an object (as with ``Car.photo``, above) 96 90 will also have a couple of extra methods: 97 91 98 ``File.save(name, content, save=True)`` 99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 92 .. method:: File.save(name, content, save=True) 100 93 101 94 Saves a new file with the file name and contents provided. This will not replace 102 95 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 once96 it. ``save`` is ``True``, the model's ``save()`` method will be called once 104 97 the file is saved. That is, these two lines:: 105 98 106 99 >>> car.photo.save('myphoto.jpg', contents, save=False) … … 110 103 111 104 >>> car.photo.save('myphoto.jpg', contents, save=True) 112 105 113 ``File.delete(save=True)`` 114 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 106 .. method:: File.delete(save=True) 115 107 116 108 Remove the file from the model instance and delete the underlying file. The 117 109 ``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()`` helper419 function.418 setting to determine the value of the :attr:`~django.core.files.File.url` 419 attribute. 420 420 421 421 This path may contain `strftime formatting`_, which will be replaced by the 422 422 date/time of the file upload (so that uploaded files don't fill up the given … … 460 460 The admin represents this field as an ``<input type="file">`` (a file-upload 461 461 widget). 462 462 463 Using a :class:`FileField` or an :class:`ImageField` (see below) in a model 463 Using a :class:`FileField` or an :class:`ImageField` (see below) in a model 464 464 takes a few steps: 465 465 466 466 1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the … … 470 470 that this directory is writable by the Web server's user account. 471 471 472 472 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 to474 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. 475 475 476 476 3. All that will be stored in your database is a path to the file 477 477 (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the 478 convenience ``get_<fieldname>_url`` function provided by Django. For479 example, if your :class:`ImageField` is called ``mug_shot``, you can get480 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 }}``. 482 482 483 483 For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and 484 484 :attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` … … 488 488 ``/home/media/photos/2007/01/15``. 489 489 490 490 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`. 491 to that file, or the file's size, you can use the 492 :attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url` 493 and :attr:`~django.core.files.File.size` attributes; see :ref:`topics-files`. 493 494 494 495 Note that whenever you deal with uploaded files, you should pay close attention 495 496 to where you're uploading them and what type of files they are, to avoid … … 575 576 Name of a model field which will be auto-populated with the height of the 576 577 image each time the model instance is saved. 577 578 578 .. attribute:: ImageField.width_field `579 .. attribute:: ImageField.width_field 579 580 580 581 Name of a model field which will be auto-populated with the width of the 581 582 image each time the model instance is saved.