File 对象

django.core.files 模块及其子模块包含了 Django 中基本的文件处理的内置类。

File

class File(file_object, name=None)[源代码]

File 类是对 Python file object 的一个简单的封装,并增加了一些 Django 特有的功能。在内部,当 Django 需要表示一个文件时,会使用这个类。

File 对象具有以下属性和方法:

  • name

    文件名,包括 MEDIA_ROOT 的相对路径。

  • size[源代码]

    文件的大小,单位为字节。

  • file

    该类封装的底层 file object

    在子类中要小心这个属性。

    一些 File 的子类,包括 ContentFileFieldFile,可以用 Python file object 以外的对象来替换这个属性。在这些情况下,这个属性本身可能是一个 File 子类(而且不一定是同一个子类)。只要有可能,就使用子类本身的属性和方法,而不是子类的 file 属性。

  • mode

    文件的读/写模式。

  • open(mode=None, *args, **kwargs)[源代码]

    打开或重新打开文件(这也会执行 File.seek(0))。mode 参数允许与 Python 内置的 open() 相同的值。*args**kwargsmode 之后传递给 Python 内置的 open()

    当重新打开一个文件时,mode 将覆盖文件原来打开的任何模式;None 表示用原来的模式重新打开。

    它可以作为一个上下文管理器使用,例如 with file.open() as f:

    Changed in Django 5.0:

    已添加支持传递 *args**kwargs

  • __iter__()[源代码]

    在文件上迭代,每次只产生一行。

  • chunks(chunk_size=None)[源代码]

    对文件进行迭代,产生给定大小的“块”。chunk_size 默认为 64KB。

    这对非常大的文件特别有用,因为它允许将它们从磁盘上串联起来,避免将整个文件存储在内存中。

  • multiple_chunks(chunk_size=None)[源代码]

    如果文件足够大,需要多个分块才能访问其所有内容,则返回 True

  • close()[源代码]

    关闭文件。

除了列出的方法外,File 还暴露了它的 file 对象的以下属性和方法:encodingfilenoflushisatencodingfilenoflushisattynewlinesreadreadintoreadlinereadlinesseektelltruncatewritewritelinesreadable()writable()seekable()

ContentFile

class ContentFile(content, name=None)[源代码]

ContentFile 类继承自 File,但与 File 不同的是,它操作的是字符串内容(也支持字节),而不是实际的文件。例如:

  1. from django.core.files.base import ContentFile
  2. f1 = ContentFile("esta frase está en español")
  3. f2 = ContentFile(b"these are bytes")

ImageFile

class ImageFile(file_object, name=None)[源代码]

Django 提供了一个专门针对图片的内置类。 django.core.files.images.ImageFile 继承了 File 的所有属性和方法,并额外提供了以下内容。

  • width[源代码]

    图像的宽度,单位为像素。

  • height[源代码]

    图像的高度,单位为像素。

附加在对象上的文件方法

任何与对象相关联的 File (如下面的 Car.photo)也会有几个额外的方法:

File.save(name, content, save=True)

使用提供的文件名和内容保存一个新文件。这不会替换现有文件,而是创建一个新文件并更新对象以指向它。如果 saveTrue,则在文件保存后将调用模型的 save() 方法。也就是说,以下两行代码:

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

等同于:

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

请注意,content 参数必须是 FileFile 的子类的实例,如 ContentFile

File.delete(save=True)

从模型实例中删除文件并删除底层文件。如果 saveTrue,一旦文件被删除,模型的 save() 方法将被调用。