Inconsistent documentation about required Storage methods

[Jaap Roes]

​https://docs.djangoproject.com/en/dev/howto/custom-file-storage/ mentions the following:

[...] but you must implement the following methods:

• Storage.delete()
• Storage.exists()
• Storage.listdir()
• Storage.size()
• Storage.url()

Yet ​https://docs.djangoproject.com/en/dev/ref/files/storage/#the-storage-class says that delete, listdir, size and url may raise NotImplementedError. Which is it?

[Baptiste Mispelon]

Hi,

Indeed, this appears to be inconsistent.
A quick look at the history of the files seem to indicate that the "topic"-style documentation is older than the reference documentation so it might have gotten out of sync.

I'm not familiar with the storage API but it seems that must could be replaced by should here.

Thanks.

[Daniele Procida]

I've marked this ticket as especially suitable for people following the ​Don't be afraid to commit tutorial at the DjangoCon US 2014 sprints. If you're tackling this ticket, please don't hesitate to ask me for guidance if you'd like any, either at the sprints themselves, or here or on the Django IRC channels, where I can be found as EvilDMP.

[Johnny Hung]

I would love to contribute to this as a beginner. I am not able to attend the sprints but I would love the feedback.

Pull request: ​https://github.com/django/django/pull/3181

Please let me know if there are any questions.

[Tim Graham]

I think it would be good to add details about things that might break if you don't implement each method.

[Daniele Procida]

I've marked this ticket as especially suitable for people following the ​​Don't be afraid to commit tutorial at the ​PyCon Ireland 2014 sprints. If you're tackling this ticket, please don't hesitate to ask me for guidance if you'd like any, either here or on the Django IRC channels, where I can be found as EvilDMP.

[Markus Holtermann]

Patch looks good to me.

[James Brewer <james@…>]

In 332706eaa02d191118966801ae4f4607a767c0eb:

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

[Daniele Procida <daniele@…>]

In d968bd5258438694b000b347a482ddcd33a9b395:

Merge pull request #3459 from brwr/brwr/django-23376

Fixed #23376 -- Make documentation about required Storage methods consistent.

[Tim Graham <timograham@…>]

In 74d0311d6b1fb3ab16072d5fad9de8b996e8af1c:

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

Backport of 332706eaa0 from master