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