File uploads documentation is patchy
|Reported by:||Daniel Pope <dan@…>||Owned by:|
|Has patch:||no||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 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.
Change History (10)
comment:1 Changed 5 years ago by jacob
- milestone set to 1.1
- Needs documentation unset
- Needs tests unset
- Patch needs improvement unset
- Triage Stage changed from Unreviewed to Accepted
comment:2 Changed 5 years ago by jacob
- Owner changed from nobody to jacob
- Status changed from new to assigned