diff options
| author | James Brewer <james@jamesbrewer.io> | 2014-11-03 01:46:38 -0800 |
|---|---|---|
| committer | James Brewer <james@jamesbrewer.io> | 2014-11-03 03:32:41 -0800 |
| commit | 332706eaa02d191118966801ae4f4607a767c0eb (patch) | |
| tree | 066187a7ba5bef1628f542ccb6aa1a624728fdc8 /docs | |
| parent | 6d0547c1ad4c370a6efb136fb3ba8422b012643f (diff) | |
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
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/howto/custom-file-storage.txt | 17 |
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: |