文件儲(chǔ)存API

獲取當(dāng)前的儲(chǔ)存類

Django提供了兩個(gè)便捷的方法來獲取當(dāng)前的儲(chǔ)存類：

class DefaultStorage[source]

DefaultStorage 提供對(duì)當(dāng)前的默認(rèn)儲(chǔ)存系統(tǒng)的延遲訪問，像DEFAULT_FILE_STORAGE中定義的那樣。DefaultStorage 內(nèi)部使用了get_storage_class()。

get_storage_class([import_path=None])[source]

返回實(shí)現(xiàn)儲(chǔ)存API的類或者模塊。

當(dāng)沒有帶著import_path 參數(shù)調(diào)用的時(shí)候， get_storage_class 會(huì)返回當(dāng)前默認(rèn)的儲(chǔ)存系統(tǒng)，像DEFAULT_FILE_STORAGE中定義的那樣。如果提供了import_path， get_storage_class會(huì)嘗試從提供的路徑導(dǎo)入類或者模塊，并且如果成功的話返回它。如果導(dǎo)入不成功會(huì)拋出異常。

FileSystemStorage類

class FileSystemStorage([location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None])[source]

FileSystemStorage類在本地文件系統(tǒng)上實(shí)現(xiàn)了基本的文件存儲(chǔ)功能。它繼承自Storage ，并且提供父類的所有公共方法的實(shí)現(xiàn)。

location

儲(chǔ)存文件的目錄的絕對(duì)路徑。默認(rèn)為MEDIA_ROOT設(shè)置的值。

base_url

在當(dāng)前位置提供文件儲(chǔ)存的URL。默認(rèn)為MEDIA_URL設(shè)置的值。

file_permissions_mode

文件系統(tǒng)的許可，當(dāng)文件保存時(shí)會(huì)接收到它。默認(rèn)為FILE_UPLOAD_PERMISSIONS。

New in Django 1.7:

新增了file_permissions_mode屬性。之前，文件總是會(huì)接收到FILE_UPLOAD_PERMISSIONS許可。

directory_permissions_mode

文件系統(tǒng)的許可，當(dāng)目錄保存時(shí)會(huì)接收到它。默認(rèn)為FILE_UPLOAD_DIRECTORY_PERMISSIONS。

New in Django 1.7:

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

注意

FileSystemStorage.delete()在提供的文件名稱不存在的時(shí)候并不會(huì)拋出任何異常。

Storage類

class Storage[source]

Storage類為文件的存儲(chǔ)提供了標(biāo)準(zhǔn)化的API，并帶有一系列默認(rèn)行為，所有其它的文件存儲(chǔ)系統(tǒng)可以按需繼承或者復(fù)寫它們。

注意

對(duì)于返回原生datetime對(duì)象的方法，所使用的有效時(shí)區(qū)為os.environ['TZ']的當(dāng)前值。要注意它總是可以通過Django的TIME_ZONE來設(shè)置。

accessed_time(name)[source]

返回包含文件的最后訪問時(shí)間的原生datetime對(duì)象。對(duì)于不能夠返回最后訪問時(shí)間的儲(chǔ)存系統(tǒng)，會(huì)拋出NotImplementedError異常。

created_time(name)[source]

返回包含文件創(chuàng)建時(shí)間的原生datetime對(duì)象。對(duì)于不能夠返回創(chuàng)建時(shí)間的儲(chǔ)存系統(tǒng)，會(huì)拋出NotImplementedError異常。

delete(name)[source]

刪除name引用的文件。如果目標(biāo)儲(chǔ)存系統(tǒng)不支持刪除操作，會(huì)拋出NotImplementedError異常。

exists(name)[source]

如果提供的名稱所引用的文件在文件系統(tǒng)中存在，則返回True，否則如果這個(gè)名稱可用于新文件，返回False。

get_available_name(name, max_length=None)[source]

返回基于name參數(shù)的文件名稱，它在目標(biāo)儲(chǔ)存系統(tǒng)中可用于寫入新的內(nèi)容。

如果提供了max_length，文件名稱長度不會(huì)超過它。如果不能找到可用的、唯一的文件名稱，會(huì)拋出SuspiciousFileOperation 異常。

如果name命名的文件已存在，一個(gè)下劃線加上隨機(jī)7個(gè)數(shù)字或字母的字符串會(huì)添加到文件名稱的末尾，擴(kuò)展名之前。

Changed in Django 1.7:

之前，下劃線和一位數(shù)字（比如"_1"，"_2"，以及其他）會(huì)添加到文件名稱的末尾，直到目標(biāo)目錄中發(fā)現(xiàn)了可用的名稱。一些惡意的用戶會(huì)利用這一確定性的算法來進(jìn)行dos攻擊。這一變化也在1.6.6， 1.5.9， 和 1.4.14中出現(xiàn)。

Changed in Django 1.8:

新增了max_length參數(shù)。

get_valid_name(name)[source]

返回基于name參數(shù)的文件名稱，它適用于目標(biāo)儲(chǔ)存系統(tǒng)。

listdir(path)[source]

列出特定目錄的所有內(nèi)容，返回一個(gè)包含2元組的列表；第一個(gè)元素是目錄，第二個(gè)是文件。對(duì)于不能夠提供列表功能的儲(chǔ)存系統(tǒng)，拋出NotImplementedError異常。

modified_time(name)[source]

返回包含最后修改時(shí)間的原生datetime對(duì)象。對(duì)于不能夠返回最后修改時(shí)間的儲(chǔ)存系統(tǒng)，拋出NotImplementedError異常。

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

通過提供的name打開文件。注意雖然返回的文件確保為File對(duì)象，但可能實(shí)際上是它的子類。在遠(yuǎn)程文件儲(chǔ)存的情況下，這意味著讀寫操作會(huì)非常慢，所以警告一下。

path(name)[source]

本地文件系統(tǒng)的路徑，文件可以用Python標(biāo)準(zhǔn)的open()在里面打開。對(duì)于不能從本地文件系統(tǒng)訪問的儲(chǔ)存系統(tǒng)，拋出NotImplementedError異常。

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

使用儲(chǔ)存系統(tǒng)來保存一個(gè)新文件，最好帶有特定的名稱。如果名稱為 name的文件已存在，儲(chǔ)存系統(tǒng)會(huì)按需修改文件名稱來獲取一個(gè)唯一的名稱。返回被儲(chǔ)存文件的實(shí)際名稱。

max_length參數(shù)會(huì)傳遞給get_available_name()。

content參數(shù)必須為django.core.files.File或者File子類的實(shí)例。

Changed in Django 1.8:

新增了max_length參數(shù)。

size(name)[source]

返回name所引用的文件的總大小，以字節(jié)為單位。對(duì)于不能夠返回文件大小的儲(chǔ)存系統(tǒng)，拋出NotImplementedError異常。

url(name)[source]

返回URL，通過它可以訪問到name所引用的文件。對(duì)于不支持通過URL訪問的儲(chǔ)存系統(tǒng)，拋出NotImplementedError異常。

譯者：Django 文檔協(xié)作翻譯小組，原文：Storage API。

本文以 CC BY-NC-SA 3.0 協(xié)議發(fā)布，轉(zhuǎn)載請(qǐng)保留作者署名和文章出處。

Django 文檔協(xié)作翻譯小組人手緊缺，有興趣的朋友可以加入我們，完全公益性質(zhì)。交流群：467338606。