django1/docs/ref/files/storage.txt

214 lines
8.3 KiB
Plaintext

================
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`.
.. attribute:: directory_permissions_mode
The file system permissions that the directory will receive when it is
saved. Defaults to :setting:`FILE_UPLOAD_DIRECTORY_PERMISSIONS`.
.. note::
The ``FileSystemStorage.delete()`` method will not raise
an exception if the given file name does not exist.
.. 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.
.. versionchanged:: 3.1
Support for :class:`pathlib.Path` was added to the
``FileSystemStorage.save()`` method.
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, or ``False`` if the name is available for a new
file.
.. 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.