Code

Opened 5 years ago

Closed 11 days ago

Last modified 11 days ago

#9535 closed Cleanup/optimization (fixed)

File uploads documentation is patchy

Reported by: Daniel Pope <dan@…> Owned by: anubhav9042
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

Description

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.

Attachments (0)

Change History (14)

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

comment:3 Changed 5 years ago by Alex

r10816 refs this.

comment:4 Changed 5 years ago by ubernostrum

  • milestone 1.1 deleted

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

comment:6 Changed 3 years ago by gabrielhurley

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 3 years ago by lukeplant

  • Severity set to Normal
  • Type set to Cleanup/optimization

comment:8 Changed 2 years ago by aaugustin

  • UI/UX unset

Change UI/UX from NULL to False.

comment:9 Changed 2 years ago by aaugustin

  • Easy pickings unset

Change Easy pickings from NULL to False.

comment:10 Changed 3 months ago by timo

  • Owner jacob deleted
  • Status changed from assigned to new
  • Version changed from 1.0 to master

comment:11 Changed 4 weeks ago by anubhav9042

  • Cc anubhav9042@… added
  • Owner set to anubhav9042
  • Status changed from new to assigned

comment:13 Changed 11 days ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

In c8c2b8a6382f255b4f0b8296906bdef8eebb5809:

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

comment:14 Changed 11 days 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

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.