文件存储 API

Getting the default storage class

Django provides convenient ways to access the default storage class:

storages

New in Django 4.2.

Storage instances as defined by STORAGES.

class DefaultStorage

DefaultStorage provides lazy access to the default storage system as defined by default key in STORAGES. DefaultStorage uses storages internally.

default_storage

default_storage is an instance of the DefaultStorage.

get_storage_class(import_path=None)

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

When called without the import_path parameter get_storage_class will return the default storage system as defined by default key in STORAGES. If import_path is provided, get_storage_class will attempt to import the class or module from the given path and will return it if successful. An exception will be raised if the import is unsuccessful.

4.2 版后已移除: The get_storage_class() function is deprecated. Use storages instead

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），这是文件的创建时间。

The InMemoryStorage class

New in Django 4.2.

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

The InMemoryStorage class implements a memory-based file storage. It has no persistence, but can be useful for speeding up tests by avoiding disk access.

  • location

    Absolute path to the directory name assigned to files. Defaults to the value of your MEDIA_ROOT setting.

  • base_url

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

  • file_permissions_mode

    The file system permissions assigned to files, provided for compatibility with FileSystemStorage. Defaults to FILE_UPLOAD_PERMISSIONS.

  • directory_permissions_mode

    The file system permissions assigned to directories, provided for compatibility with FileSystemStorage. Defaults to 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_TZ 为 True，则返回一个处理过的 datetime，否则返回一个当地时区的未处理的 datetime。

  • get_alternative_name(file_root, file_ext)

    根据 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。

    如果 USE_TZ 为 True，则返回一个处理过的 datetime，否则返回一个当地时区的未处理的 datetime。

  • get_modified_time(name)

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

    如果 USE_TZ 为 True，则返回一个处理过的 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。