diff --git a/docs/faq/usage.txt b/docs/faq/usage.txt index 67565a5807f65..6e1f0dac3d7f9 100644 --- a/docs/faq/usage.txt +++ b/docs/faq/usage.txt @@ -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: - - #. 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. - - #. 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. - - #. 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__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 }}``. +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, 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 :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 :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 }}``. diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index aa037f7c2a8d6..e864a7e0042ce 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -12,109 +12,110 @@ The ``File`` object Django's ``File`` has the following attributes and methods: -``File.path`` -~~~~~~~~~~~~~ +.. attribute:: File.name -The absolute path to the file's location on a local filesystem. + The name of file including the relative path from :setting:`MEDIA_ROOT`. -:ref:`Custom file storage systems ` may not store -files locally; files stored on these systems will have a ``path`` of ``None``. +.. attribute:: File.path -``File.url`` -~~~~~~~~~~~~ + The absolute path to the file's location on a local filesystem. -The URL where the file can be retrieved. This is often useful in :ref:`templates -`; for example, a bit of a template for displaying a ``Car`` -(see above) might look like:: + :ref:`Custom file storage systems ` may not store + files locally; files stored on these systems will have a ``path`` of + ``None``. - {{ car.name }} +.. attribute:: File.url -``File.size`` -~~~~~~~~~~~~~ + The URL where the file can be retrieved. This is often useful in + :ref:`templates `; for example, a bit of a template for + displaying a ``Car`` (see above) might look like: + + .. code-block:: html+django -The size of the file in bytes. + {{ car.name }} -``File.open(mode=None)`` -~~~~~~~~~~~~~~~~~~~~~~~~ +.. attribute:: File.size -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()``. + The size of the file in bytes. -When reopening a file, ``mode`` will override whatever mode the file was -originally opened with; ``None`` means to reopen with the original mode. +.. method:: File.open(mode=None) -``File.read(num_bytes=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()``. -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. + When reopening a file, ``mode`` will override whatever mode the file was + originally opened with; ``None`` means to reopen with the original mode. -``File.__iter__()`` -~~~~~~~~~~~~~~~~~~~ +.. method:: File.read(num_bytes=None) -Iterate over the file yielding one line at a time. + 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.chunks(chunk_size=None)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: File.__iter__() -Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults -to 64 KB. + Iterate over the file yielding one line at a time. -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. +.. method:: File.chunks(chunk_size=None) -``File.multiple_chunks(chunk_size=None)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Iterate over the file yielding "chunks" of a given size. ``chunk_size`` + defaults to 64 KB. -Returns ``True`` if the file is large enough to require multiple chunks to -access all of its content give some ``chunk_size``. + 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.write(content)`` -~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: File.multiple_chunks(chunk_size=None) -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. + Returns ``True`` if the file is large enough to require multiple chunks to + access all of its content give some ``chunk_size``. -``File.close()`` -~~~~~~~~~~~~~~~~ +.. method:: File.write(content) -Close 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. + +.. method:: File.close() + + Close the file. Additional ``ImageField`` attributes ------------------------------------ -``File.width`` and ``File.height`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. attribute:: File.width + + Width of the image. + +.. attribute:: File.height -These attributes provide the dimensions of the image. + 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: - -``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:: - - >>> car.photo.save('myphoto.jpg', contents, save=False) - >>> car.save() +.. highlight:: pycon -are the same as this one line:: +Any :class:`File` that's associated with an object (as with ``Car.photo``, +above) will also have a couple of extra methods: - >>> car.photo.save('myphoto.jpg', contents, save=True) +.. method:: File.save(name, content, save=True) -Note that the ``content`` argument must be an instance of -:class:`File` or of a subclass of :class:`File`. + 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() + + are the same as this one line:: + + >>> car.photo.save('myphoto.jpg', contents, save=True) + + 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. + Remove the file from the model instance and delete the underlying file. The + ``save`` argument works as above. diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 370c0284df3f9..8412f02d73810 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -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__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__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.