儲存API · Django 中文文檔 1.8

# 文件儲存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 文檔協作翻譯小組](http://python.usyiyi.cn/django/index.html)，原文：[Storage API](https://docs.djangoproject.com/en/1.8/ref/files/storage/)。 > > 本文以 [CC BY-NC-SA 3.0](http://creativecommons.org/licenses/by-nc-sa/3.0/cn/) 協議發布，轉載請保留作者署名和文章出處。 > > [Django 文檔協作翻譯小組](http://python.usyiyi.cn/django/index.html)人手緊缺，有興趣的朋友可以加入我們，完全公益性質。交流群：467338606。