# Django 3.2.11.dev 文档

# 文件存储 API

## 获取当前存储类

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

class `DefaultStorage`

  `DefaultStorage` 在内部使用 `get_storage_class()`，提供对当前默认存储系统的惰性访问，该系统由 `DEFAULT_FILE_STORAGE` 定义。

`get_storage_class`(import_path=None)

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

  当调用时没有提供 `import_path` 参数时，`get_storage_class` 将返回当前默认的存储系统，定义为 `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`

    存放文件的目录的绝对路径。 默认为你的 `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），这是文件的创建时间。

Changed in Django 3.1:

在 `FileSystemStorage.save()` 方法中增加了对 `pathlib.Path` 的支持。

## `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`。