mirror of
https://github.com/django/django.git
synced 2024-12-25 10:35:48 +00:00
88e13b44ed
This is derived from the current behaviour of FileSystemStorage. Note that since this was not previously documented, other implementations may not currently conform.
190 lines
7.1 KiB
Plaintext
190 lines
7.1 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`.
|
|
|
|
.. 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)
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
.. 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)
|
|
|
|
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.
|