文件存储 API — Django 文档

文件存储API

获取当前存储类

Django 提供了两种方便的方式来访问当前的存储类：

class DefaultStorage

DefaultStorage 提供对当前默认存储系统的延迟访问，如 :setting:`DEFAULT_FILE_STORAGE` 所定义。 DefaultStorage 在内部使用 get_storage_class()。

get_storage_class(import_path=None)

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

在没有 import_path 参数的情况下调用时，get_storage_class 将返回由 :setting:`DEFAULT_FILE_STORAGE` 定义的当前默认存储系统。 如果提供了 import_path，get_storage_class 将尝试从给定路径导入类或模块，如果成功将返回它。 如果导入不成功，将引发异常。

FileSystemStorage 类

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

FileSystemStorage 类在本地文件系统上实现基本文件存储。 它继承自 Storage 并为其所有公共方法提供实现。

location

将保存文件的目录的绝对路径。 默认为您的 :setting:`MEDIA_ROOT` 设置的值。

base_url

提供存储在此位置的文件的 URL。 默认为您的 :setting:`MEDIA_URL` 设置的值。

file_permissions_mode

文件在保存时将获得的文件系统权限。 默认为 :setting:`FILE_UPLOAD_PERMISSIONS`。

directory_permissions_mode

目录在保存时将获得的文件系统权限。 默认为 :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS`。

笔记

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

get_created_time(name)

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

3.1 版更改： 对 pathlib.Path 的支持已添加到 FileSystemStorage.save() 方法中。

Storage 类

class Storage

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

笔记

当方法返回朴素的 datetime 对象时，使用的有效时区将是 os.environ['TZ'] 的当前值； 请注意，这通常是从 Django 的 :setting:`TIME_ZONE` 设置的。

delete(name)

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

exists(name)

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

get_accessed_time(name)

返回文件最后访问时间的 datetime。 对于无法返回上次访问时间的存储系统，这将引发 NotImplementedError。

如果 :setting:`USE_TZ` 是 True，则返回一个有意识的 datetime，否则返回一个本地时区的朴素 datetime。

get_alternative_name(file_root, file_ext)

3.0 版中的新功能。

返回基于 file_root 和 file_ext 参数的替代文件名，下划线加上随机的 7 个字符的字母数字字符串附加到文件名的扩展名之前。

get_available_name(name, max_length=None)

返回基于 name 参数的文件名，该文件名是免费的，可用于写入目标存储系统上的新内容。

如果提供，文件名的长度不会超过 max_length。 如果找不到可用的唯一文件名，则会引发 SuspiciousFileOperation 异常。

如果已存在带有 name 的文件，则调用 get_alternative_name() 以获取替代名称。

get_created_time(name)

返回文件创建时间的 datetime。 对于无法返回创建时间的存储系统，这将引发 NotImplementedError。

如果 :setting:`USE_TZ` 是 True，则返回一个有意识的 datetime，否则返回一个本地时区的朴素 datetime。

get_modified_time(name)

返回文件最后修改时间的 datetime。 对于无法返回上次修改时间的存储系统，这将引发 NotImplementedError。

如果 :setting:`USE_TZ` 是 True，则返回一个有意识的 datetime，否则返回一个本地时区的朴素 datetime。

get_valid_name(name)

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

generate_filename(filename)

通过调用 get_valid_name() 验证 filename 并返回要传递给 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。