django/docs/ref/files/storage.txt

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

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

Getting the default storage class
=================================

Django provides convenient ways to access the default storage class:

.. data:: storages

    A dictionary-like object that allows retrieving a storage instance using
    its alias as defined by :setting:`STORAGES`.

    ``storages`` has an attribute ``backends``, which defaults to the raw value
    provided in :setting:`STORAGES`.

    Additionally, ``storages`` provides a ``create_storage()`` method that
    accepts the dictionary used in :setting:`STORAGES` for a backend, and
    returns a storage instance based on that backend definition. This may be
    useful for third-party packages needing to instantiate storages in tests:

    .. code-block:: pycon

        >>> from django.core.files.storage import storages
        >>> storages.backends
        {'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'},
         'staticfiles': {'BACKEND': 'django.contrib.staticfiles.storage.StaticFilesStorage'},
         'custom': {'BACKEND': 'package.storage.CustomStorage'}}
        >>> storage_instance = storages.create_storage({"BACKEND": "package.storage.CustomStorage"})

.. class:: DefaultStorage

    :class:`~django.core.files.storage.DefaultStorage` provides
    lazy access to the default storage system as defined by ``default`` key in
    :setting:`STORAGES`. :class:`DefaultStorage` uses
    :data:`~django.core.files.storage.storages` internally.

.. data:: default_storage

    :data:`~django.core.files.storage.default_storage` is an instance of the
    :class:`~django.core.files.storage.DefaultStorage`.

The ``FileSystemStorage`` class
===============================

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

    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.

    .. note::

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

    .. 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`.

    .. attribute:: directory_permissions_mode

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

    .. attribute:: allow_overwrite

        .. versionadded:: 5.1

        Flag to control allowing saving a new file over an existing one.
        Defaults to ``False``.

    .. method:: get_created_time(name)

        Returns a :class:`~datetime.datetime` of the system's ctime, i.e.
        :func:`os.path.getctime`. On some systems (like Unix), this is the
        time of the last metadata change, and on others (like Windows), it's
        the creation time of the file.

The ``InMemoryStorage`` class
=============================

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

    The :class:`~django.core.files.storage.InMemoryStorage` class implements
    a memory-based file storage. It has no persistence, but can be useful for
    speeding up tests by avoiding disk access.

    .. attribute:: location

        Absolute path to the directory name assigned to 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 assigned to files, provided for
        compatibility with ``FileSystemStorage``. Defaults to
        :setting:`FILE_UPLOAD_PERMISSIONS`.

    .. attribute:: directory_permissions_mode

        The file system permissions assigned to directories, provided for
        compatibility with ``FileSystemStorage``. Defaults to
        :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS`.

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::
        When methods return 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:: 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.

    .. method:: get_accessed_time(name)

        Returns a :class:`~datetime.datetime` of the last accessed time of the
        file. For storage systems unable to return the last accessed time this
        will raise :exc:`NotImplementedError`.

        If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
        otherwise returns a naive ``datetime`` in the local timezone.

    .. method:: get_alternative_name(file_root, file_ext)

        Returns an alternative filename based on the ``file_root`` and
        ``file_ext`` parameters, an underscore plus a random 7 character
        alphanumeric string is appended to the filename before the extension.

    .. 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, :meth:`get_alternative_name` is
        called to obtain an alternative name.

    .. method:: get_created_time(name)

        Returns a :class:`~datetime.datetime` of the creation time of the file.
        For storage systems unable to return the creation time this will raise
        :exc:`NotImplementedError`.

        If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
        otherwise returns a naive ``datetime`` in the local timezone.

    .. method:: get_modified_time(name)

        Returns a :class:`~datetime.datetime` of the last modified time of the
        file. For storage systems unable to return the last modified time this
        will raise :exc:`NotImplementedError`.

        If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
        otherwise returns a naive ``datetime`` in the local timezone.

    .. method:: get_valid_name(name)

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

    .. method:: generate_filename(filename)

        Validates the ``filename`` by calling :attr:`get_valid_name()` and
        returns a filename to be passed to the :meth:`save` method.

        The ``filename`` argument may include a path as returned by
        :attr:`FileField.upload_to <django.db.models.FileField.upload_to>`.
        In that case, the path won't be passed to :attr:`get_valid_name()` but
        will be prepended back to the resulting name.

        The default implementation uses :mod:`os.path` operations. Override
        this method if that's not appropriate for your storage.

    .. 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:: 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 a file-like object that can be
        wrapped in ``File``.

    .. 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.