文件存储 API — Django 文档

来自菜鸟教程
Django/docs/2.2.x/ref/files/storage
跳转至:导航、​搜索

文件存储 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_pathget_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)上,这是文件的创建时间。


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_available_name(name, max_length=None)

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

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

如果已存在带有 name 的文件,则会在文件名的扩展名之前附加一个下划线和一个随机的 7 个字符的字母数字字符串。

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