/docs/ref/files/storage.txt

https://code.google.com/p/mango-py/ · Plain Text · 143 lines · 96 code · 47 blank · 0 comment · 0 complexity · 5a906754201999480ae8001b1b04c94d MD5 · raw file

  1. File storage API
  2. ================
  3. .. module:: django.core.files.storage
  4. Getting the current storage class
  5. ---------------------------------
  6. Django provides two convenient ways to access the current storage class:
  7. .. class:: DefaultStorage
  8. :class:`~django.core.files.storage.DefaultStorage` provides
  9. lazy access to the current default storage system as defined by
  10. :setting:`DEFAULT_FILE_STORAGE`. :class:`DefaultStorage` uses
  11. :func:`~django.core.files.storage.get_storage_class` internally.
  12. .. function:: get_storage_class([import_path=None])
  13. Returns a class or module which implements the storage API.
  14. When called without the ``import_path`` parameter ``get_storage_class``
  15. will return the current default storage system as defined by
  16. :setting:`DEFAULT_FILE_STORAGE`. If ``import_path`` is provided,
  17. ``get_storage_class`` will attempt to import the class or module from the
  18. given path and will return it if successful. An exception will be
  19. raised if the import is unsuccessful.
  20. The FileSystemStorage Class
  21. ---------------------------
  22. .. class:: FileSystemStorage
  23. The :class:`~django.core.files.storage.FileSystemStorage` class implements
  24. basic file storage on a local filesystem. It inherits from
  25. :class:`~django.core.files.storage.Storage` and provides implementations
  26. for all the public methods thereof.
  27. .. note::
  28. The :class:`FileSystemStorage.delete` method will not raise
  29. raise an exception if the given file name does not exist.
  30. The Storage Class
  31. -----------------
  32. .. class:: Storage
  33. The :class:`~django.core.files.storage.Storage` class provides a
  34. standardized API for storing files, along with a set of default
  35. behaviors that all other storage systems can inherit or override
  36. as necessary.
  37. .. method:: accessed_time(name)
  38. .. versionadded:: 1.3
  39. Returns a ``datetime`` object containing the last accessed time of the
  40. file. For storage systems that aren't able to return the last accessed
  41. time this will raise ``NotImplementedError`` instead.
  42. .. method:: created_time(name)
  43. .. versionadded:: 1.3
  44. Returns a ``datetime`` object containing the creation time of the file.
  45. For storage systems that aren't able to return the creation time this
  46. will raise ``NotImplementedError`` instead.
  47. .. method:: delete(name)
  48. Deletes the file referenced by ``name``. If deletion is not supported
  49. on the targest storage system this will raise ``NotImplementedError``
  50. instead
  51. .. method:: exists(name)
  52. Returns ``True`` if a file referenced by the given name already exists
  53. in the storage system, or ``False`` if the name is available for a new
  54. file.
  55. .. method:: get_available_name(name)
  56. Returns a filename based on the ``name`` parameter that's free and
  57. available for new content to be written to on the target storage
  58. system.
  59. .. method:: get_valid_name(name)
  60. Returns a filename based on the ``name`` parameter that's suitable
  61. for use on the target storage system.
  62. .. method:: listdir(path)
  63. Lists the contents of the specified path, returning a 2-tuple of lists;
  64. the first item being directories, the second item being files. For
  65. storage systems that aren't able to provide such a listing, this will
  66. raise a ``NotImplementedError`` instead.
  67. .. method:: modified_time(name)
  68. .. versionadded:: 1.3
  69. Returns a ``datetime`` object containing the last modified time. For
  70. storage systems that aren't able to return the last modified time, this
  71. will raise ``NotImplementedError`` instead.
  72. .. method:: open(name, mode='rb')
  73. Opens the file given by ``name``. Note that although the returned file
  74. is guaranteed to be a ``File`` object, it might actually be some
  75. subclass. In the case of remote file storage this means that
  76. reading/writing could be quite slow, so be warned.
  77. .. method:: path(name)
  78. The local filesystem path where the file can be opened using Python's
  79. standard ``open()``. For storage systems that aren't accessible from
  80. the local filesystem, this will raise ``NotImplementedError`` instead.
  81. .. method:: save(name, content)
  82. Saves a new file using the storage system, preferably with the name
  83. specified. If there already exists a file with this name ``name``, the
  84. storage system may modify the filename as necessary to get a unique
  85. name. The actual name of the stored file will be returned.
  86. The ``content`` argument must be an instance of
  87. :class:`django.core.files.File` or of a subclass of
  88. :class:`~django.core.files.File`.
  89. .. method:: size(name)
  90. Returns the total size, in bytes, of the file referenced by ``name``.
  91. For storage systems that aren't able to return the file size this will
  92. raise ``NotImplementedError`` instead.
  93. .. method:: url(name)
  94. Returns the URL where the contents of the file referenced by ``name``
  95. can be accessed. For storage systems that don't support access by URL
  96. this will raise ``NotImplementedError`` instead.