Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

144 lines (96 sloc) 5.306 kB
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
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 :class:`FileSystemStorage.delete` method will not raise
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.
.. method:: accessed_time(name)
.. versionadded:: 1.3
Returns a ``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)
.. versionadded:: 1.3
Returns a ``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 targest 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)
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.
.. 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)
.. versionadded:: 1.3
Returns a ``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)
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 ``content`` argument must be an instance of
:class:`django.core.files.File` or of a subclass of
:class:`~django.core.files.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.
Jump to Line
Something went wrong with that request. Please try again.