File uploads documentation is patchy

[Daniel Pope <dan@…>]

I've been working on a new file upload interface for my application, and I notice that since the file upload refactor and the documentation refactor, the file uploads documentation fails to adequately answer simple questions about file upload workflows - everything has to be patched together from various reference information: the "File Uploads" page, the "Managing Files", models.File/ImageField, forms.File/ImageField, and (the hardest to find) "The File Object".

I believe, first and foremost, the documentation does not adequately describe how to save uploaded files to models, ie. use of instance.field.save().

However more generally I think the "File Uploads" page keeps going off on a tangent about UploadedFile APIs and UploadHandler APIs. These should be documented in full elsewhere, so that the "File Uploads" page could simply cover common workflows:

• Uploading files via forms.ModelForm (far and away the most straightforward approach and worth covering first).
• Saving uploaded files to a models.FileField, retrieving them again and deleting them.
• Accessing uploaded files - what to find in request.FILES.
• Processing uploaded files - reading chunks or lines.
• Default upload handler behaviour (with further discussion of upload handlers on some other page)

I notice one misleading comment which is tangential to this ticket. Many browsers just submit the content type for uploaded files as 'application/octet-stream'. Therefore the comment alongside UploadedFile.content_type is misleading: "trust but verify" approach is not wrong or right but simply won't produce useful results.

[Alex Gaynor]

r10816 refs this.

[James Bennett]

While I agree better documentation is needed here, this ticket represents a request for a rather large chunk of it and 1.1 needs to get out the door.

[onelson]

This just came up on the mailing list, and as I started to look at the problem I found the docs in pretty much the same state today (a year on from the last update).
The required reading to work with file uploads (and File/Image model fields) is spread around on the following pages:

• ​http://docs.djangoproject.com/en/dev/ref/files/file/
• ​http://docs.djangoproject.com/en/dev/topics/http/file-uploads/
• ​http://docs.djangoproject.com/en/dev/topics/files/
• ​http://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.FileField

If people are happy with the idea of taking the http/file-uploads topic and expanding there, we can probably reduce the mystery a bit by adding some additional examples. Personally, when it comes to working with models.FileField.save() directly, my initial stumbling block was I didn't get that contents argument needed to be an instance of django.core.files.File rather than a regular file object. This is mentioned quietly.

[Gabriel Hurley]

I find myself dealing with the docs related to Django's file handling APIs a lot lately for one reason or another. It seems to be a corner of the docs that have languished for some time. As such, I'm in complete agreement that this can be improved substantially.

Organizationally, A lot of what's in topics/http/file-uploads belongs in a reference document. It's a pet peeve of mine when the only reference for entire classes winds up in a topic or how-to guide. FileUploadHandler and UploadedFile ought to be spec'd out somewhere else.

With those bits moved out of the way, the topic guide can then focus on the nitty gritty of how to actually accomplish things using those APIs rather than just showing them to you.

All of the bits mentioned in the ticket description and in the comments would make worthy additions to the document. I'm happy to review patches if anyone wants to take a stab at it.

[Aymeric Augustin]

Change UI/UX from NULL to False.

[Aymeric Augustin]

Change Easy pickings from NULL to False.

[ANUBHAV JOSHI]

​https://github.com/django/django/pull/2479

[Tim Graham <timograham@…>]

In c8c2b8a6382f255b4f0b8296906bdef8eebb5809:

Fixed #9535 -- Added a reference guide for file upload classes.

[Tim Graham <timograham@…>]

In d9c7d9eb6ebbf92098787c127bb3e64f85978cca:

[1.7.x] Fixed #9535 -- Added a reference guide for file upload classes.

Backport of c8c2b8a638 from master