Browse Source

Fixed #23376 -- Made documentation about required Storage methods
consistent.

The following methods **should** be implemented, but are not required:

* Storage.delete()
* Storage.exists()
* Storage.listdir()
* Storage.size()
* Storage.url()

Updated documentation to reflect this fact and give a couple of examples
where some methods may not be implemented. Add a warning that not
implementing some methods will result in a partial (possibly broken)
interface.

Ticket: https://code.djangoproject.com/ticket/23376

James Brewer 10 years ago
parent
commit
332706eaa0
1 changed files with 15 additions and 2 deletions
  1. 15 2
      docs/howto/custom-file-storage.txt

+ 15 - 2
docs/howto/custom-file-storage.txt

@@ -41,8 +41,8 @@ You'll need to follow these steps:
    ``django.utils.deconstruct.deconstructible`` class decorator for this
    (that's what Django uses on FileSystemStorage).
 
-Your custom storage system may override any of the storage methods explained in
-:doc:`/ref/files/storage`, but you **must** implement the following methods:
+By default, the following methods raise `NotImplementedError` and will
+typically have to be overridden:
 
 * :meth:`Storage.delete`
 * :meth:`Storage.exists`
@@ -50,6 +50,19 @@ Your custom storage system may override any of the storage methods explained in
 * :meth:`Storage.size`
 * :meth:`Storage.url`
 
+Note however that not all these methods are required and may be deliberately 
+omitted. As it happens, it is possible to leave each method unimplemented and
+still have a working Storage.
+
+By way of example, if listing the contents of certain storage backends turns
+out to be expensive, you might decide not to implement `Storage.listdir`.
+
+Another example would be a backend that only handles writing to files. In this
+case, you would not need to implement any of the above methods.
+
+Ultimately, which of these methods are implemented is up to you. Leaving some
+methods unimplemented will result in a partial (possibly broken) interface.
+
 You'll also usually want to use hooks specifically designed for custom storage
 objects. These are: