/docs/ref/files/storage.txt
Plain Text | 143 lines | 96 code | 47 blank | 0 comment | 0 complexity | 5a906754201999480ae8001b1b04c94d MD5 | raw file
Possible License(s): BSD-3-Clause
1File storage API 2================ 3 4.. module:: django.core.files.storage 5 6Getting the current storage class 7--------------------------------- 8 9Django provides two convenient ways to access the current storage class: 10 11.. class:: DefaultStorage 12 13 :class:`~django.core.files.storage.DefaultStorage` provides 14 lazy access to the current default storage system as defined by 15 :setting:`DEFAULT_FILE_STORAGE`. :class:`DefaultStorage` uses 16 :func:`~django.core.files.storage.get_storage_class` internally. 17 18.. function:: get_storage_class([import_path=None]) 19 20 Returns a class or module which implements the storage API. 21 22 When called without the ``import_path`` parameter ``get_storage_class`` 23 will return the current default storage system as defined by 24 :setting:`DEFAULT_FILE_STORAGE`. If ``import_path`` is provided, 25 ``get_storage_class`` will attempt to import the class or module from the 26 given path and will return it if successful. An exception will be 27 raised if the import is unsuccessful. 28 29The FileSystemStorage Class 30--------------------------- 31 32.. class:: FileSystemStorage 33 34 The :class:`~django.core.files.storage.FileSystemStorage` class implements 35 basic file storage on a local filesystem. It inherits from 36 :class:`~django.core.files.storage.Storage` and provides implementations 37 for all the public methods thereof. 38 39 .. note:: 40 41 The :class:`FileSystemStorage.delete` method will not raise 42 raise an exception if the given file name does not exist. 43 44The Storage Class 45----------------- 46 47.. class:: Storage 48 49 The :class:`~django.core.files.storage.Storage` class provides a 50 standardized API for storing files, along with a set of default 51 behaviors that all other storage systems can inherit or override 52 as necessary. 53 54 .. method:: accessed_time(name) 55 56 .. versionadded:: 1.3 57 58 Returns a ``datetime`` object containing the last accessed time of the 59 file. For storage systems that aren't able to return the last accessed 60 time this will raise ``NotImplementedError`` instead. 61 62 .. method:: created_time(name) 63 64 .. versionadded:: 1.3 65 66 Returns a ``datetime`` object containing the creation time of the file. 67 For storage systems that aren't able to return the creation time this 68 will raise ``NotImplementedError`` instead. 69 70 .. method:: delete(name) 71 72 Deletes the file referenced by ``name``. If deletion is not supported 73 on the targest storage system this will raise ``NotImplementedError`` 74 instead 75 76 .. method:: exists(name) 77 78 Returns ``True`` if a file referenced by the given name already exists 79 in the storage system, or ``False`` if the name is available for a new 80 file. 81 82 .. method:: get_available_name(name) 83 84 Returns a filename based on the ``name`` parameter that's free and 85 available for new content to be written to on the target storage 86 system. 87 88 89 .. method:: get_valid_name(name) 90 91 Returns a filename based on the ``name`` parameter that's suitable 92 for use on the target storage system. 93 94 .. method:: listdir(path) 95 96 Lists the contents of the specified path, returning a 2-tuple of lists; 97 the first item being directories, the second item being files. For 98 storage systems that aren't able to provide such a listing, this will 99 raise a ``NotImplementedError`` instead. 100 101 .. method:: modified_time(name) 102 103 .. versionadded:: 1.3 104 105 Returns a ``datetime`` object containing the last modified time. For 106 storage systems that aren't able to return the last modified time, this 107 will raise ``NotImplementedError`` instead. 108 109 .. method:: open(name, mode='rb') 110 111 Opens the file given by ``name``. Note that although the returned file 112 is guaranteed to be a ``File`` object, it might actually be some 113 subclass. In the case of remote file storage this means that 114 reading/writing could be quite slow, so be warned. 115 116 .. method:: path(name) 117 118 The local filesystem path where the file can be opened using Python's 119 standard ``open()``. For storage systems that aren't accessible from 120 the local filesystem, this will raise ``NotImplementedError`` instead. 121 122 .. method:: save(name, content) 123 124 Saves a new file using the storage system, preferably with the name 125 specified. If there already exists a file with this name ``name``, the 126 storage system may modify the filename as necessary to get a unique 127 name. The actual name of the stored file will be returned. 128 129 The ``content`` argument must be an instance of 130 :class:`django.core.files.File` or of a subclass of 131 :class:`~django.core.files.File`. 132 133 .. method:: size(name) 134 135 Returns the total size, in bytes, of the file referenced by ``name``. 136 For storage systems that aren't able to return the file size this will 137 raise ``NotImplementedError`` instead. 138 139 .. method:: url(name) 140 141 Returns the URL where the contents of the file referenced by ``name`` 142 can be accessed. For storage systems that don't support access by URL 143 this will raise ``NotImplementedError`` instead.