Author: gabrielhurley Date: 2010-12-05 00:46:23 -0600 (Sun, 05 Dec 2010) New Revision: 14832
Modified: django/branches/releases/1.2.X/docs/ref/files/storage.txt django/branches/releases/1.2.X/docs/ref/settings.txt Log: [1.2.X] 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. Backport of [14831] from trunk. Modified: django/branches/releases/1.2.X/docs/ref/files/storage.txt =================================================================== --- django/branches/releases/1.2.X/docs/ref/files/storage.txt 2010-12-05 06:45:34 UTC (rev 14831) +++ django/branches/releases/1.2.X/docs/ref/files/storage.txt 2010-12-05 06:46:23 UTC (rev 14832) @@ -1,52 +1,119 @@ 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.size(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. -Returns the total size, in bytes, of the file referenced by ``name``. +.. function:: get_storage_class([import_path=None]) -``Storage.url(name)`` -~~~~~~~~~~~~~~~~~~~~~ + 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. -Returns the URL where the contents of the file referenced by ``name`` can be -accessed. +The FileSystemStorage Class +--------------------------- -``Storage.open(name, mode='rb')`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. class:: FileSystemStorage -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. + 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.save(name, content)`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The Storage Class +----------------- -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. +.. class:: Storage -The ``content`` argument must be an instance of -:class:`django.core.files.File` or of a subclass of -:class:`~django.core.files.File`. + 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.delete(name)`` -~~~~~~~~~~~~~~~~~~~~~~~~ + .. method:: delete(name) -Deletes the file referenced by ``name``. This method won't raise an exception if -the file doesn't exist. + 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 referened 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 ale 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) + + 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. Modified: django/branches/releases/1.2.X/docs/ref/settings.txt =================================================================== --- django/branches/releases/1.2.X/docs/ref/settings.txt 2010-12-05 06:45:34 UTC (rev 14831) +++ django/branches/releases/1.2.X/docs/ref/settings.txt 2010-12-05 06:46:23 UTC (rev 14832) @@ -608,7 +608,7 @@ 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`. -- You received this message because you are subscribed to the Google Groups "Django updates" group. To post to this group, send email to django-upda...@googlegroups.com. To unsubscribe from this group, send email to django-updates+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-updates?hl=en.
