The ``File`` object

فهرست فصل‌ها دانلود آرشیوناشر

Django Docs · نسخهٔ 33d2e5948a0b · BSD-3-Clause

===================

The `File` object

The django.core.files module and its submodules contain built-in classes for basic file handling in Django.

The `File` class

The File class is a thin wrapper around a Python file object with some Django-specific additions. Internally, Django uses this class when it needs to represent a file.

File objects have the following attributes and methods:

The name of the file including the relative path from MEDIA_ROOT.

The size of the file in bytes.

The underlying file object that this class wraps.

Some subclasses of File, including ~django.core.files.base.ContentFile and ~django.db.models.fields.files.FieldFile, may replace this attribute with an object other than a Python file object. In these cases, this attribute may itself be a File subclass (and not necessarily the same subclass). Whenever possible, use the attributes and methods of the subclass itself rather than the those of the subclass's `file` attribute.

The read/write mode for the file.

Open or reopen the file (which also does `File.seek(0)). The mode argument allows the same values as Python's built-in python:open(). *args and **kwargs are passed after mode to Python's built-in python:open`.

When reopening a file, `mode will override whatever mode the file was originally opened with; None` means to reopen with the original mode.

It can be used as a context manager, e.g. `with file.open() as f:`.

Iterate over the file yielding one line at a time.

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.

Returns `True if the file is large enough to require multiple chunks to access all of its content give some chunk_size`.

Close the file.

In addition to the listed methods, ~django.core.files.File exposes the following attributes and methods of its `file object: encoding, fileno, flush, isatty, newlines, read, readinto, readline, readlines, seek, tell, truncate, write, writelines, readable(), writable(), and seekable()`.

The `ContentFile` class

The `ContentFile class inherits from ~django.core.files.File, but unlike ~django.core.files.File` it operates on string content (bytes also supported), rather than an actual file. For example::

from django.core.files.base import ContentFile

f1 = ContentFile("esta frase está en español") f2 = ContentFile(b"these are bytes")

The `ImageFile` class

Django provides a built-in class specifically for images. django.core.files.images.ImageFile inherits all the attributes and methods of ~django.core.files.File, and additionally provides the following:

Width of the image in pixels.

Height of the image in pixels.

Additional methods on files attached to objects

Any File that is associated with an object (as with `Car.photo`, below) will also have a couple of extra methods:

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:

pycon
    >>> car.photo.save("myphoto.jpg", content, save=False)
    >>> car.save()

are equivalent to:

.. code-block:: pycon

    >>> car.photo.save("myphoto.jpg", content, save=True)

Note that the ``content`` argument must be an instance of either

Removes the file from the model instance and deletes the underlying file. If `save is True, the model's save()` method will be called once the file is deleted.