From 332706eaa02d191118966801ae4f4607a767c0eb Mon Sep 17 00:00:00 2001 From: James Brewer Date: Mon, 3 Nov 2014 01:46:38 -0800 Subject: [PATCH] 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 --- 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: