From 0ab50aad36f849d710a0ac053a99eb058e489e24 Mon Sep 17 00:00:00 2001 From: Gabriel Hurley Date: Sun, 5 Dec 2010 06:45:34 +0000 Subject: [PATCH] Fixed #13605 -- Improved documentation of the django.core.files.storage module. Added documentation for DefaultStorage, get_storage_class, FileSystemStorage, and some missing public methods on Storage. New metadata targets included for everything. Thanks to kopernikus for the report and elbarto for contributing to the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@14831 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/files/storage.txt | 168 +++++++++++++++++++++++++------------ docs/ref/settings.txt | 2 +- 2 files changed, 117 insertions(+), 53 deletions(-) diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt index b27ea1556b1..923a098bc4d 100644 --- a/docs/ref/files/storage.txt +++ b/docs/ref/files/storage.txt @@ -1,79 +1,143 @@ File storage API ================ -``Storage.exists(name)`` -~~~~~~~~~~~~~~~~~~~~~~~~ +.. module:: django.core.files.storage -``True`` if a file exists given some ``name``. +Getting the current storage class +--------------------------------- -``Storage.path(name)`` -~~~~~~~~~~~~~~~~~~~~~~ +Django provides two convenient ways to access the current storage class: -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. +.. class:: DefaultStorage -``Storage.accessed_time(name)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + :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. -.. versionadded:: 1.3 +.. function:: get_storage_class([import_path=None]) -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. + 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. -``Storage.created_time(name)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The FileSystemStorage Class +--------------------------- -.. versionadded:: 1.3 +.. class:: FileSystemStorage -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. + 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. -``Storage.modified_time(name)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The Storage Class +----------------- -.. versionadded:: 1.3 +.. class:: Storage -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. + 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. -``Storage.size(name)`` -~~~~~~~~~~~~~~~~~~~~~~ + .. method:: accessed_time(name) -Returns the total size, in bytes, of the file referenced by ``name``. + .. versionadded:: 1.3 -``Storage.url(name)`` -~~~~~~~~~~~~~~~~~~~~~ + 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. -Returns the URL where the contents of the file referenced by ``name`` can be -accessed. + .. method:: created_time(name) -``Storage.open(name, mode='rb')`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. versionadded:: 1.3 -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. + 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. -``Storage.save(name, content)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. method:: delete(name) -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. + Deletes the file referenced by ``name``. If deletion is not supported + on the targest storage system this will raise ``NotImplementedError`` + instead -The ``content`` argument must be an instance of -:class:`django.core.files.File` or of a subclass of -:class:`~django.core.files.File`. + .. method:: exists(name) -``Storage.delete(name)`` -~~~~~~~~~~~~~~~~~~~~~~~~ + Returns ``True`` if a file referened by the given name already exists + in the storage system, or ``False`` if the name is available for a new + file. -Deletes the file referenced by ``name``. This method won't raise an exception if -the file doesn't exist. + .. 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 ale 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. diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index bfc2dbf66f9..47fa486fe0e 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -655,7 +655,7 @@ isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the DEFAULT_FILE_STORAGE -------------------- -Default: ``'django.core.files.storage.FileSystemStorage'`` +Default: :class:`django.core.files.storage.FileSystemStorage` Default file storage class to be used for any file-related operations that don't specify a particular storage system. See :doc:`/topics/files`.