118 lines
3.3 KiB
Plaintext
118 lines
3.3 KiB
Plaintext
.. _ref-files-file:
|
|
|
|
The ``File`` object
|
|
===================
|
|
|
|
.. currentmodule:: django.core.files
|
|
|
|
.. class:: File(file_object)
|
|
|
|
``File`` attributes and methods
|
|
-------------------------------
|
|
|
|
Django's ``File`` has the following attributes and methods:
|
|
|
|
``File.path``
|
|
~~~~~~~~~~~~~
|
|
|
|
The absolute path to the file's location on a local filesystem.
|
|
|
|
:ref:`Custom file storage systems <howto-custom-file-storage>` may not store
|
|
files locally; files stored on these systems will have a ``path`` of ``None``.
|
|
|
|
``File.url``
|
|
~~~~~~~~~~~~
|
|
|
|
The URL where the file can be retrieved. This is often useful in :ref:`templates
|
|
<topics-templates>`; for example, a bit of a template for displaying a ``Car``
|
|
(see above) might look like::
|
|
|
|
<img src='{{ car.photo.url }}' alt='{{ car.name }}' />
|
|
|
|
``File.size``
|
|
~~~~~~~~~~~~~
|
|
|
|
The size of the file in bytes.
|
|
|
|
``File.open(mode=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()``.
|
|
|
|
When reopening a file, ``mode`` will override whatever mode the file was
|
|
originally opened with; ``None`` means to reopen with the original mode.
|
|
|
|
``File.read(num_bytes=None)``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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.__iter__()``
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Iterate over the file yielding one line at a time.
|
|
|
|
``File.chunks(chunk_size=None)``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Iterate over the file yielding "chunks" of a given size. ``chunk_size`` defaults
|
|
to 64 KB.
|
|
|
|
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.multiple_chunks(chunk_size=None)``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Returns ``True`` if the file is large enough to require multiple chunks to
|
|
access all of its content give some ``chunk_size``.
|
|
|
|
``File.write(content)``
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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.
|
|
|
|
``File.close()``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Close the file.
|
|
|
|
Additional ``ImageField`` attributes
|
|
------------------------------------
|
|
|
|
``File.width`` and ``File.height``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
These attributes provide the dimensions 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()
|
|
|
|
are the same as this one line::
|
|
|
|
>>> car.photo.save('myphoto.jpg', contents, save=True)
|
|
|
|
``File.delete(save=True)``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Remove the file from the model instance and delete the underlying file. The
|
|
``save`` argument works as above.
|