test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
This commit is contained in:
Gabriel Hurley 2010-12-05 06:45:34 +00:00
parent 01f2081bb6
commit 0ab50aad36
2 changed files with 117 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

168
docs/ref/files/storage.txt
View File

@ -1,79 +1,143 @@
File storage API 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 .. class:: DefaultStorage
``open()``. For storage systems that aren't accessible from the local
filesystem, this will raise ``NotImplementedError`` instead.
``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. Returns a class or module which implements the storage API.
For storage systems that aren't able to return the last accessed time, this
will raise ``NotImplementedError`` instead. 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. The :class:`~django.core.files.storage.FileSystemStorage` class implements
For storage systems that aren't able to return the creation time, this basic file storage on a local filesystem. It inherits from
will raise ``NotImplementedError`` instead. :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 The :class:`~django.core.files.storage.Storage` class provides a
systems that aren't able to return the last modified time, this will raise standardized API for storing files, along with a set of default
``NotImplementedError`` instead. 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 .. method:: created_time(name)
accessed.
``Storage.open(name, mode='rb')`` .. versionadded:: 1.3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Opens the file given by ``name``. Note that although the returned file is Returns a ``datetime`` object containing the creation time of the file.
guaranteed to be a ``File`` object, it might actually be some subclass. In the For storage systems that aren't able to return the creation time this
case of remote file storage this means that reading/writing could be quite slow, will raise ``NotImplementedError`` instead.
so be warned.
``Storage.save(name, content)`` .. method:: delete(name)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Saves a new file using the storage system, preferably with the name specified. Deletes the file referenced by ``name``. If deletion is not supported
If there already exists a file with this name ``name``, the storage system may on the targest storage system this will raise ``NotImplementedError``
modify the filename as necessary to get a unique name. The actual name of the instead
stored file will be returned.
The ``content`` argument must be an instance of .. method:: exists(name)
:class:`django.core.files.File` or of a subclass of
:class:`~django.core.files.File`.
``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 .. method:: get_available_name(name)
the file doesn't exist.
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.

2
docs/ref/settings.txt
View File

@ -655,7 +655,7 @@ isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the
DEFAULT_FILE_STORAGE 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 Default file storage class to be used for any file-related operations that don't
specify a particular storage system. See :doc:`/topics/files`. specify a particular storage system. See :doc:`/topics/files`.