id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
9535	File uploads documentation is patchy	Daniel Pope <dan@…>	ANUBHAV JOSHI	"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."	Cleanup/optimization	closed	Documentation	dev	Normal	fixed		anubhav9042@…	Accepted	1	0	0	0	0	0