You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
121 lines
3.6 KiB
121 lines
3.6 KiB
.. _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: |
|
|
|
.. attribute:: File.name |
|
|
|
The name of file including the relative path from :setting:`MEDIA_ROOT`. |
|
|
|
.. attribute:: 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``. |
|
|
|
.. attribute:: 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: |
|
|
|
.. code-block:: html+django |
|
|
|
<img src='{{ car.photo.url }}' alt='{{ car.name }}' /> |
|
|
|
.. attribute:: File.size |
|
|
|
The size of the file in bytes. |
|
|
|
.. method:: 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. |
|
|
|
.. method:: 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. |
|
|
|
.. method:: File.__iter__() |
|
|
|
Iterate over the file yielding one line at a time. |
|
|
|
.. method:: 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. |
|
|
|
.. method:: 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``. |
|
|
|
.. method:: 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. |
|
|
|
.. method:: File.close() |
|
|
|
Close the file. |
|
|
|
Additional ``ImageField`` attributes |
|
------------------------------------ |
|
|
|
.. attribute:: File.width |
|
|
|
Width of the image. |
|
|
|
.. attribute:: File.height |
|
|
|
Heigght of the image. |
|
|
|
Additional methods on files attached to objects |
|
----------------------------------------------- |
|
|
|
.. highlight:: pycon |
|
|
|
Any :class:`File` that's associated with an object (as with ``Car.photo``, |
|
above) will also have a couple of extra methods: |
|
|
|
.. method:: 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) |
|
|
|
Note that the ``content`` argument must be an instance of |
|
:class:`File` or of a subclass of :class:`File`. |
|
|
|
.. method:: File.delete(save=True) |
|
|
|
Remove the file from the model instance and delete the underlying file. The |
|
``save`` argument works as above.
|
|
|