[1.7.x] Fixed #23376 -- Clarified that certain Storage methods should be implemented but are not required.

Backport of 332706eaa0 from master
This commit is contained in:
James Brewer 2014-11-03 01:46:38 -08:00 committed by Tim Graham
parent 3ac46d0726
commit 74d0311d6b
1 changed files with 15 additions and 2 deletions

View File

@ -41,8 +41,8 @@ You'll need to follow these steps:
``django.utils.deconstruct.deconstructible`` class decorator for this ``django.utils.deconstruct.deconstructible`` class decorator for this
(that's what Django uses on FileSystemStorage). (that's what Django uses on FileSystemStorage).
Your custom storage system may override any of the storage methods explained in By default, the following methods raise `NotImplementedError` and will
:doc:`/ref/files/storage`, but you **must** implement the following methods: typically have to be overridden:
* :meth:`Storage.delete` * :meth:`Storage.delete`
* :meth:`Storage.exists` * :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.size`
* :meth:`Storage.url` * :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 You'll also usually want to use hooks specifically designed for custom storage
objects. These are: objects. These are: