/docs/ref/files/storage.txt

  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.