django 1.8 官方文檔翻譯： 3-3-3 檔案儲存API

檔案儲存API

擷取目前的儲存類

Django提供了兩個便捷的方法來擷取目前的儲存類：

class DefaultStorage[source]

DefaultStorage

提供對目前的預設儲存系統的延遲通路，像

DEFAULT_FILE_STORAGE

中定義的那樣。

DefaultStorage

内部使用了

get_storage_class()

。

get_storage_class([import_path=None])[source]

傳回實作儲存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])[source]

FileSystemStorage

類在本地檔案系統上實作了基本的檔案存儲功能。它繼承自

Storage

，并且提供父類的所有公共方法的實作。

location

儲存檔案的目錄的絕對路徑。預設為

MEDIA_ROOT

設定的值。

base_url

在目前位置提供檔案儲存的URL。預設為

MEDIA_URL

file_permissions_mode

檔案系統的許可，當檔案儲存時會接收到它。預設為

FILE_UPLOAD_PERMISSIONS

New in Django 1.7:

新增了file_permissions_mode屬性。之前，檔案總是會接收到FILE_UPLOAD_PERMISSIONS許可。           

directory_permissions_mode

檔案系統的許可，當目錄儲存時會接收到它。預設為

FILE_UPLOAD_DIRECTORY_PERMISSIONS

New in Django 1.7:

新增了directory_permissions_mode屬性。之前，目錄總是會接收到FILE_UPLOAD_DIRECTORY_PERMISSIONS許可。           

注意

FileSystemStorage.delete()

在提供的檔案名稱不存在的時候并不會抛出任何異常。

Storage類

class Storage[source]

Storage

類為檔案的存儲提供了标準化的API，并帶有一系列預設行為，所有其它的檔案存儲系統可以按需繼承或者複寫它們。

對于傳回原生

datetime

對象的方法，所使用的有效時區為

os.environ['TZ']

的目前值。要注意它總是可以通過Django的

TIME_ZONE

來設定。

accessed_time(name)[source]

傳回包含檔案的最後通路時間的原生

datetime

對象。對于不能夠傳回最後通路時間的儲存系統，會抛出

NotImplementedError

異常。

created_time(name)[source]

傳回包含檔案建立時間的原生

datetime

對象。對于不能夠傳回建立時間的儲存系統，會抛出

NotImplementedError

delete(name)[source]

删除

name

引用的檔案。如果目标儲存系統不支援删除操作，會抛出

NotImplementedError

exists(name)[source]

如果提供的名稱所引用的檔案在檔案系統中存在，則傳回

True

，否則如果這個名稱可用于新檔案，傳回

False

get_available_name(name, max_length=None)[source]

傳回基于

name

參數的檔案名稱，它在目标儲存系統中可用于寫入新的内容。

如果提供了

max_length

，檔案名稱長度不會超過它。如果不能找到可用的、唯一的檔案名稱，會抛出

SuspiciousFileOperation

如果

name

命名的檔案已存在，一個下劃線加上随機7個數字或字母的字元串會添加到檔案名稱的末尾，擴充名之前。

Changed in Django 1.7:

之前，下劃線和一位數字（比如"_1"，"_2"，以及其他）會添加到檔案名稱的末尾，直到目标目錄中發現了可用的名稱。一些惡意的使用者會利用這一确定性的算法來進行dos攻擊。這一變化也在1.6.6， 1.5.9， 和 1.4.14中出現。           

Changed in Django 1.8:

新增了max_length參數。           

get_valid_name(name)[source]

name

參數的檔案名稱，它适用于目标儲存系統。

listdir(path)[source]

列出特定目錄的所有内容，傳回一個包含2元組的清單；第一個元素是目錄，第二個是檔案。對于不能夠提供清單功能的儲存系統，抛出

NotImplementedError

modified_time(name)[source]

傳回包含最後修改時間的原生

datetime

對象。對于不能夠傳回最後修改時間的儲存系統，抛出

NotImplementedError

open(name, mode='rb')[source]

通過提供的

name

打開檔案。注意雖然傳回的檔案確定為

File

對象，但可能實際上是它的子類。在遠端檔案儲存的情況下，這意味着讀寫操作會非常慢，是以警告一下。

path(name)[source]

本地檔案系統的路徑，檔案可以用Python标準的

open()

在裡面打開。對于不能從本地檔案系統通路的儲存系統，抛出

NotImplementedError

save(name, content, max_length=None)[source]

使用儲存系統來儲存一個新檔案，最好帶有特定的名稱。如果名稱為

name

的檔案已存在，儲存系統會按需修改檔案名稱來擷取一個唯一的名稱。傳回被儲存檔案的實際名稱。

max_length參數會傳遞給

get_available_name()

content

參數必須為

django.core.files.File

或者

File

子類的執行個體。

Changed in Django 1.8:

新增了max_length參數。           

size(name)[source]

傳回

name

所引用的檔案的總大小，以位元組為機關。對于不能夠傳回檔案大小的儲存系統，抛出

NotImplementedError

url(name)[source]

傳回URL，通過它可以通路到

name

所引用的檔案。對于不支援通過URL通路的儲存系統，抛出

NotImplementedError

譯者： Django 文檔協作翻譯小組 ，原文： Storage API 本文以 CC BY-NC-SA 3.0 協定釋出，轉載請保留作者署名和文章出處。 人手緊缺，有興趣的朋友可以加入我們，完全公益性質。交流群：467338606。