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