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
parent
01f2081bb6
commit
0ab50aad36
|
|
@ -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.
|
||||
|
||||
``Storage.created_time(name)``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
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.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
The FileSystemStorage Class
|
||||
---------------------------
|
||||
|
||||
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.
|
||||
.. class:: FileSystemStorage
|
||||
|
||||
``Storage.modified_time(name)``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
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.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
.. note::
|
||||
|
||||
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:`FileSystemStorage.delete` method will not raise
|
||||
raise an exception if the given file name does not exist.
|
||||
|
||||
``Storage.size(name)``
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
The Storage Class
|
||||
-----------------
|
||||
|
||||
Returns the total size, in bytes, of the file referenced by ``name``.
|
||||
.. class:: Storage
|
||||
|
||||
``Storage.url(name)``
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
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.
|
||||
|
||||
Returns the URL where the contents of the file referenced by ``name`` can be
|
||||
accessed.
|
||||
.. method:: accessed_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 last accessed time of the
|
||||
file. For storage systems that aren't able to return the last accessed
|
||||
time this will raise ``NotImplementedError`` instead.
|
||||
|
||||
``Storage.save(name, content)``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. method:: created_time(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.
|
||||
.. versionadded:: 1.3
|
||||
|
||||
The ``content`` argument must be an instance of
|
||||
:class:`django.core.files.File` or of a subclass of
|
||||
:class:`~django.core.files.File`.
|
||||
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.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:: 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.
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue