1 File storage API

     2 ================

     3 

     4 .. module:: django.core.files.storage

     5 

     6 Getting the current storage class

     7 ---------------------------------

     8 

     9 Django 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 

    29 The 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 

    44 The 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:: delete(name)

    55 

    56         Deletes the file referenced by ``name``. If deletion is not supported

    57         on the targest storage system this will raise ``NotImplementedError``

    58         instead

    59 

    60     .. method:: exists(name)

    61 

    62         Returns ``True`` if a file referened by the given name already exists

    63         in the storage system, or ``False`` if the name is available for a new

    64         file.

    65 

    66     .. method:: get_available_name(name)

    67 

    68         Returns a filename based on the ``name`` parameter that's free and

    69         available for new content to be written to on the target storage

    70         system.

    71 

    72 

    73     .. method:: get_valid_name(name)

    74 

    75         Returns a filename based on the ``name`` parameter that's suitable

    76         for use on the target storage system.

    77 

    78     .. method:: listdir(path)

    79 

    80         Lists the contents of the specified path, returning a 2-tuple of lists;

    81         the first item being directories, the second item being files. For

    82         storage systems that aren't able to provide such a listing, this will

    83         raise a ``NotImplementedError`` instead.

    84 

    85     .. method:: open(name, mode='rb')

    86 

    87         Opens the file given by ``name``. Note that although the returned file

    88         is guaranteed to be a ``File`` object, it might actually be some

    89         subclass. In the case of remote file storage this means that

    90         reading/writing could be quite slow, so be warned.

    91 

    92     .. method:: path(name)

    93 

    94         The local filesystem path where the file can be opened using Python's

    95         standard ``open()``. For storage systems that aren't accessible from

    96         the local filesystem, this will raise ``NotImplementedError`` instead.

    97 

    98     .. method:: save(name, content)

    99 

   100         Saves a new file using the storage system, preferably with the name

   101         specified. If there already exists a file with this name ``name``, the

   102         storage system may modify the filename as necessary to get a unique

   103         name. The actual name of the stored file will be returned.

   104 

   105         The ``content`` argument must be an instance of

   106         :class:`django.core.files.File` or of a subclass of

   107         :class:`~django.core.files.File`.

   108 

   109     .. method:: size(name)

   110 

   111         Returns the total size, in bytes, of the file referenced by ``name``.

   112         For storage systems that aren't able to return the file size this will

   113         raise ``NotImplementedError`` instead.

   114 

   115     .. method:: url(name)

   116 

   117         Returns the URL where the contents of the file referenced by ``name``

   118         can be accessed. For storage systems that don't support access by URL

   119         this will raise ``NotImplementedError`` instead.