File storage API
================

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

Getting the current storage class
---------------------------------

Django provides two convenient ways to access the current storage class:

.. class:: DefaultStorage

    :class:`~django.core.files.storage.DefaultStorage` provides
    lazy access to the current default storage system as defined by
    :setting:`DEFAULT_FILE_STORAGE`. :class:`DefaultStorage` uses
    :func:`~django.core.files.storage.get_storage_class` internally.

.. function:: get_storage_class(import_path=None)

    Returns a class or module which implements the storage API.

    When called without the ``import_path`` parameter ``get_storage_class``
    will return the current default storage system as defined by
    :setting:`DEFAULT_FILE_STORAGE`. If ``import_path`` is provided,
    ``get_storage_class`` will attempt to import the class or module from the
    given path and will return it if successful. An exception will be
    raised if the import is unsuccessful.

The FileSystemStorage Class
---------------------------

.. class:: FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

    The :class:`~django.core.files.storage.FileSystemStorage` class implements
    basic file storage on a local filesystem. It inherits from
    :class:`~django.core.files.storage.Storage` and provides implementations
    for all the public methods thereof.

    .. attribute:: location

        Absolute path to the directory that will hold the files.
        Defaults to the value of your :setting:`MEDIA_ROOT` setting.

    .. attribute:: base_url

        URL that serves the files stored at this location.
        Defaults to the value of your :setting:`MEDIA_URL` setting.

    .. attribute:: file_permissions_mode

        The file system permissions that the file will receive when it is
        saved. Defaults to :setting:`FILE_UPLOAD_PERMISSIONS`.

        .. versionadded:: 1.7

            The ``file_permissions_mode`` attribute was added. Previously files
            always received :setting:`FILE_UPLOAD_PERMISSIONS` permissions.

    .. attribute:: directory_permissions_mode

        The file system permissions that the directory will receive when it is
        saved. Defaults to :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS`.

        .. versionadded:: 1.7

            The ``directory_permissions_mode`` attribute was added. Previously
            directories always received
            :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS` permissions.

    .. note::

        The ``FileSystemStorage.delete()`` method will not raise
        an exception if the given file name does not exist.

The Storage Class
-----------------

.. class:: Storage

    The :class:`~django.core.files.storage.Storage` class provides a
    standardized API for storing files, along with a set of default
    behaviors that all other storage systems can inherit or override
    as necessary.

    .. note::
        For methods returning naive ``datetime`` objects, the
        effective timezone used will be the current value of
        ``os.environ['TZ']``; note that this is usually set from
        Django's :setting:`TIME_ZONE`.

    .. method:: accessed_time(name)

        Returns a naive ``datetime`` object containing the last
        accessed time of the file. For storage systems that aren't
        able to return the last accessed time this will raise
        ``NotImplementedError`` instead.

    .. method:: created_time(name)

        Returns a naive ``datetime`` object containing the creation
        time of the file.  For storage systems that aren't able to
        return the creation time this will raise
        ``NotImplementedError`` instead.

    .. method:: delete(name)

        Deletes the file referenced by ``name``. If deletion is not supported
        on the target storage system this will raise ``NotImplementedError``
        instead

    .. method:: exists(name)

        Returns ``True`` if a file referenced by the given name already exists
        in the storage system, or ``False`` if the name is available for a new
        file.

    .. method:: get_available_name(name, max_length=None)

        Returns a filename based on the ``name`` parameter that's free and
        available for new content to be written to on the target storage
        system.

        The length of the filename will not exceed ``max_length``, if provided.
        If a free unique filename cannot be found, a
        :exc:`SuspiciousFileOperation
        <django.core.exceptions.SuspiciousOperation>` exception will be raised.

        If a file with ``name`` already exists, an underscore plus a random
        7 character alphanumeric string is appended to the filename before
        the extension.

        .. versionchanged:: 1.7

            Previously, an underscore followed by a number (e.g. ``"_1"``,
            ``"_2"``, etc.) was appended to the filename until an available
            name in the destination directory was found. A malicious user could
            exploit this deterministic algorithm to create a denial-of-service
            attack. This change was also made in Django 1.6.6, 1.5.9, and
            1.4.14.

        .. versionchanged:: 1.8

            The ``max_length`` argument was added.

    .. method:: get_valid_name(name)

        Returns a filename based on the ``name`` parameter that's suitable
        for use on the target storage system.

    .. method:: listdir(path)

        Lists the contents of the specified path, returning a 2-tuple of lists;
        the first item being directories, the second item being files. For
        storage systems that aren't able to provide such a listing, this will
        raise a ``NotImplementedError`` instead.

    .. method:: modified_time(name)

        Returns a naive ``datetime`` object containing the last
        modified time. For storage systems that aren't able to return
        the last modified time, this will raise
        ``NotImplementedError`` instead.

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

        Opens the file given by ``name``. Note that although the returned file
        is guaranteed to be a ``File`` object, it might actually be some
        subclass. In the case of remote file storage this means that
        reading/writing could be quite slow, so be warned.

    .. method:: path(name)

        The local filesystem path where the file can be opened using Python's
        standard ``open()``. For storage systems that aren't accessible from
        the local filesystem, this will raise ``NotImplementedError`` instead.

    .. method:: save(name, content, max_length=None)

        Saves a new file using the storage system, preferably with the name
        specified. If there already exists a file with this name ``name``, the
        storage system may modify the filename as necessary to get a unique
        name. The actual name of the stored file will be returned.

        The ``max_length`` argument is passed along to
        :meth:`get_available_name`.

        The ``content`` argument must be an instance of
        :class:`django.core.files.File` or of a subclass of
        :class:`~django.core.files.File`.

        .. versionchanged:: 1.8

            The ``max_length`` argument was added.

    .. method:: size(name)

        Returns the total size, in bytes, of the file referenced by ``name``.
        For storage systems that aren't able to return the file size this will
        raise ``NotImplementedError`` instead.

    .. method:: url(name)

        Returns the URL where the contents of the file referenced by ``name``
        can be accessed. For storage systems that don't support access by URL
        this will raise ``NotImplementedError`` instead.