文件存储 API

获取默认的存储类:

Django 提供了便捷的方式来访问默认的存储类:

storages

New in Django 4.2.

STORAGES 定义的存储实例。

class DefaultStorage

DefaultStorage 提供了对由 STORAGES 中的 default 键定义的默认存储系统的延迟访问。DefaultStorage 内部使用了 storages

default_storage

default_storageDefaultStorage 的一个实例。

get_storage_class(import_path=None)

返回一个实现存储 API 的类或模块。

当没有提供 import_path 参数调用时,get_storage_class 将返回由 STORAGES 中的 default 键定义的默认存储系统。如果提供了 import_pathget_storage_class 将尝试从给定路径导入类或模块,如果成功将返回它。如果导入失败,则会引发异常。

4.2 版后已移除: get_storage_class() 函数已被弃用。请改用 storages

FileSystemStorage

class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

FileSystemStorage 类实现了本地文件系统的基本文件存储。它继承自 Storage 类,并提供了其中所有公开方法的实现。

  • location

    存放文件的目录的绝对路径。 默认为你的 MEDIA_ROOT 配置的值。

  • base_url

    为存储在此位置的文件提供服务的 URL。默认为你的 MEDIA_URL 配置的值。

  • file_permissions_mode

    保存文件时,文件系统将获得的权限。默认为 FILE_UPLOAD_PERMISSIONS

  • directory_permissions_mode

    保存目录时,该目录将获得的文件系统权限,默认为 FILE_UPLOAD_DIRECTORY_PERMISSIONS

备注

如果给定的文件名不存在,FileSystemStorage.delete() 方法不会引发异常。

  • get_created_time(name)

    返回系统 ctime 的 datetime,即 os.path.getctime()。在某些系统上(如 Unix),这是最后一次修改元数据的时间,而在其他系统上(如 Windows),这是文件的创建时间。

InMemoryStorage

New in Django 4.2.

class InMemoryStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

InMemoryStorage 类实现了基于内存的文件存储。它没有持久性,但可以通过避免磁盘访问来加速测试。

  • location

    文件分配的目录名称的绝对路径。默认值为 MEDIA_ROOT 设置的值。

  • base_url

    为存储在此位置的文件提供服务的 URL。默认为你的 MEDIA_URL 配置的值。

  • file_permissions_mode

    文件系统分配给文件的文件系统权限,为了与 FileSystemStorage 兼容而提供。默认值为 FILE_UPLOAD_PERMISSIONS

  • directory_permissions_mode

    文件系统分配给目录的文件系统权限,为了与 FileSystemStorage 兼容而提供。默认值为 FILE_UPLOAD_DIRECTORY_PERMISSIONS

Storage

class Storage

Storage 类为存储文件提供了一个标准化的 API,以及一组默认行为,所有其他存储系统可以根据需要继承或覆盖。

备注

当方法返回未处理的 datetime 对象时,所使用的有效时区将是 os.environ['TZ'] 的当前值;注意,这通常是由 Django 的 TIME_ZONE 设置的。

  • delete(name)

    删除 name 引用的文件。如果目标存储系统不支持删除,这将引发 NotImplementedError

  • exists(name)

    如果给定名称所引用的文件已经存在于存储系统中,则返回 True;如果该名称可用于新文件,则返回 False

  • get_accessed_time(name)

    返回文件最后访问时间的 datetime。对于不能返回最后访问时间的存储系统,将引发 NotImplementedError

    如果 USE_TZTrue,则返回一个处理过的 datetime,否则返回一个当地时区的未处理的 datetime

  • get_alternative_name(file_root, file_ext)

    根据 file_rootfile_ext 参数返回一个替代的文件名,一个下划线加上一个随机的 7 个字符的字母数字字符串被附加到文件名的扩展名之前。

  • get_available_name(name, max_length=None)

    返回一个基于 name 参数的文件名,该文件名在目标存储系统中是空闲的,可供新内容写入。

    文件名的长度不会超过 max_length,如果提供的话。如果不能找到一个空闲的唯一文件名,将引发一个 SuspiciousFileOperation 异常。

    如果一个带有 name 的文件已经存在,则调用 get_alternative_name() 来获得一个替代名称。

  • get_created_time(name)

    返回文件的创建时间的 datetime。对于不能返回创建时间的存储系统,将引发 NotImplementedError

    如果 USE_TZTrue,则返回一个处理过的 datetime,否则返回一个当地时区的未处理的 datetime

  • get_modified_time(name)

    返回文件最后修改时间的 datetime。对于不能返回最后修改时间的存储系统,将引发 NotImplementedError

    如果 USE_TZTrue,则返回一个处理过的 datetime,否则返回一个当地时区的未处理的 datetime

  • get_valid_name(name)

    根据 name 参数返回一个适合在目标存储系统中使用的文件名。

  • generate_filename(filename)

    通过调用 get_valid_name() 验证 文件名,并返回一个文件名传给 save() 方法。

    filename 参数可能包含 FileField.upload_to 返回的路径。在这种情况下,路径不会被传递给 get_valid_name(),而是会被预输入到结果的名称中。

    默认实现使用 os.path 操作。如果不适合你的存储,请重写这个方法。

  • listdir(path)

    列出指定路径的内容,返回一个二元元组列表,第一项是目录,第二项是文件。对于不能提供这种列表的存储系统,这将引发一个 NotImplementedError

  • open(name, mode=’rb’)

    打开由 name 给出的文件。请注意,虽然返回的文件保证是一个 File 对象,但实际上它可能是某个子类。在远程文件存储的情况下,这意味着读/写可能会很慢,所以要注意。

  • path(name)

    本地文件系统路径,在这里可以使用 Python 的标准 open() 打开文件。对于不能从本地文件系统访问的存储系统,这将引发 NotImplementedError

  • save(name, content, max_length=None)

    使用存储系统保存一个新的文件,最好使用指定的名称。如果已经存在一个带有这个名字 name 的文件,存储系统可以根据需要修改文件名以获得一个唯一的名字。将返回存储文件的实际名称。

    max_length 参数被传递给 get_available_name()

    content 参数必须是 django.core.files.File 的实例,或者是一个可以用 File 包装的类文件对象。

  • size(name)

    返回 name 引用的文件的总大小,以字节为单位。对于不能返回文件大小的存储系统,将引发 NotImplementedError

  • url(name)

    返回可以访问 name 引用的文件内容的URL。对于不支持通过 URL 访问的存储系统,这将引发 NotImplementedError