Opened 12 years ago

Closed 6 years ago

Last modified 6 years ago

#9535 closed Cleanup/optimization (fixed)

File uploads documentation is patchy

Reported by: Daniel Pope <dan@…> Owned by: ANUBHAV JOSHI
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: anubhav9042@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


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

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.

Change History (14)

comment:1 Changed 12 years ago by Jacob

milestone: 1.1
Triage Stage: UnreviewedAccepted

comment:2 Changed 12 years ago by Jacob

Owner: changed from nobody to Jacob
Status: newassigned

comment:3 Changed 11 years ago by Alex Gaynor

r10816 refs this.

comment:4 Changed 11 years ago by James Bennett

milestone: 1.1

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.

comment:5 Changed 10 years ago by 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:

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 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.

comment:6 Changed 10 years ago by 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.

comment:7 Changed 9 years ago by Luke Plant

Severity: Normal
Type: Cleanup/optimization

comment:8 Changed 9 years ago by Aymeric Augustin

UI/UX: unset

Change UI/UX from NULL to False.

comment:9 Changed 9 years ago by Aymeric Augustin

Easy pickings: unset

Change Easy pickings from NULL to False.

comment:10 Changed 7 years ago by Tim Graham

Owner: Jacob deleted
Status: assignednew
Version: 1.0master

comment:11 Changed 7 years ago by ANUBHAV JOSHI

Cc: anubhav9042@… added
Owner: set to ANUBHAV JOSHI
Status: newassigned

comment:12 Changed 7 years ago by ANUBHAV JOSHI

Has patch: set

comment:13 Changed 6 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In c8c2b8a6382f255b4f0b8296906bdef8eebb5809:

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

comment:14 Changed 6 years ago by Tim Graham <timograham@…>

In d9c7d9eb6ebbf92098787c127bb3e64f85978cca:

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

Backport of c8c2b8a638 from master

Note: See TracTickets for help on using tickets.
Back to Top