Merge pull request #3459 from brwr/brwr/django-23376

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

1 files changed, 15 insertions, 2 deletions

diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt
index 56aa479a22..9b217b8031 100644
--- a/docs/howto/custom-file-storage.txt
+++ b/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: