From 74d0311d6b1fb3ab16072d5fad9de8b996e8af1c Mon Sep 17 00:00:00 2001 From: James Brewer Date: Mon, 3 Nov 2014 01:46:38 -0800 Subject: [PATCH] [1.7.x] Fixed #23376 -- Clarified that certain Storage methods should be implemented but are not required. Backport of 332706eaa0 from master --- docs/howto/custom-file-storage.txt | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) 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: