File uploads documentation is patchy
|Reported by:||Owned by:||ANUBHAV JOSHI|
|Has patch:||yes||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||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
- 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 8 years ago by
|Patch needs improvement:||unset|
|Triage Stage:||Unreviewed → Accepted|
comment:11 Changed 3 years ago by
|Owner:||set to ANUBHAV JOSHI|
|Status:||new → assigned|