# Django 5.2.8 documentation

# 文件存储 API

## 获取默认的存储类：

Django 提供了便捷的方式来访问默认的存储类：

storages

  一个类似字典的对象，允许使用 `STORAGES` 中定义的别名检索存储实例。

  `storages` 有一个属性 `backends`，它默认为 `STORAGES` 中提供的原始值。

  此外，`storages` 提供了一个 `create_storage()` 方法，它接受 `STORAGES` 中用于后端的字典，并返回基于该后端定义的存储实例。这对于需要在测试中实例化存储的第三方包可能很有用：

      >>> from django.core.files.storage import storages
      >>> storages.backends
      {'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'},
       'staticfiles': {'BACKEND': 'django.contrib.staticfiles.storage.StaticFilesStorage'},
       'custom': {'BACKEND': 'package.storage.CustomStorage'}}
      >>> storage_instance = storages.create_storage({"BACKEND": "package.storage.CustomStorage"})

class DefaultStorage

  `DefaultStorage` 提供了对由 `STORAGES` 中的 `default` 键定义的默认存储系统的延迟访问。`DefaultStorage` 内部使用了 `storages`。

default_storage

  `default_storage` 是 `DefaultStorage` 的一个实例。

## `FileSystemStorage` 类

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

  `FileSystemStorage` 类实现了本地文件系统的基本文件存储。它继承自 `Storage` 类，并提供了其中所有公开方法的实现。

  Note

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

  location

    存放文件的目录的绝对路径。 默认为你的 `MEDIA_ROOT` 配置的值。

  base_url

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

  file_permissions_mode

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

  directory_permissions_mode

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

  allow_overwrite

    控制是否允许保存新文件覆盖现有文件的标志。默认为 `False`。

  get_created_time(name)

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

## `InMemoryStorage` 类

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

  `InMemoryStorage` 类实现了基于内存的文件存储。它没有持久性，但可以通过避免磁盘访问来加速测试。

  location

    文件分配的目录名称的绝对路径。默认值为 `MEDIA_ROOT` 设置的值。

  base_url

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

  file_permissions_mode

    文件系统分配给文件的文件系统权限，为了与 `FileSystemStorage` 兼容而提供。默认值为 `FILE_UPLOAD_PERMISSIONS`。

  directory_permissions_mode

    文件系统分配给目录的文件系统权限，为了与 `FileSystemStorage` 兼容而提供。默认值为 `FILE_UPLOAD_DIRECTORY_PERMISSIONS`。

## `Storage` 类

class Storage

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

  Note

  当方法返回未处理的 `datetime` 对象时，所使用的有效时区将是 `os.environ['TZ']` 的当前值；注意，这通常是由 Django 的 `TIME_ZONE` 设置的。

  delete(name)

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

  exists(name)

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

  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)

    Validates the `filename` by calling `get_valid_name` and returns a filename to be passed to the `save()` method.

    The `filename` argument may include a path as returned by `FileField.upload_to`. In that case, the path won't be passed to `get_valid_name` but will be prepended back to the resulting 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`。

There are community-maintained solutions too!

Django has a vibrant ecosystem. There are storage backends highlighted on the Community Ecosystem page. The Django Packages Storage Backends grid has even more options for you!