#36587: Incorrect sentence in documentation about upload handlers
-----------------------------------+------------------------------------
Reporter: Baptiste Mispelon | Owner: (none)
Type: Bug | Status: new
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-----------------------------------+------------------------------------
Changes (by Natalia Bidart):
* stage: Unreviewed => Accepted
Old description:
> The documentation about changing upload handlers on the fly [1] states:
>
> For instance, suppose you’ve written a ProgressBarUploadHandler that
> provides feedback on upload progress to some sort of AJAX widget. You’d
> add this handler to your upload handlers like this:
> `request.upload_handlers.insert(0, ProgressBarUploadHandler(request))`
> You’d probably want to use `list.insert()` in this case (instead of
> `append()`) because a progress bar handler would need to run before any
> other handlers. Remember, the upload handlers are processed in order.
>
> The part that says "You'd probably want to use list.insert [...] (instead
> of append)" is incorrect, since the example is already using
> `list.insert`. The sentence should just say something like:
>
> We use `list.insert` to make sure the progress bar handler is run
> before any other handlers, since the upload handlers are processed in
> order.
New description:
The documentation about [https://docs.djangoproject.com/en/5.2/topics/http
/file-uploads/#modifying-upload-handlers-on-the-fly changing upload
handlers on the fly] states:
For instance, suppose you’ve written a ProgressBarUploadHandler that
provides feedback on upload progress to some sort of AJAX widget. You’d
add this handler to your upload handlers like this:
`request.upload_handlers.insert(0, ProgressBarUploadHandler(request))`
You’d probably want to use `list.insert()` in this case (instead of
`append()`) because a progress bar handler would need to run before any
other handlers. Remember, the upload handlers are processed in order.
The part that says "You'd probably want to use list.insert [...] (instead
of append)" is incorrect, since the example is already using
`list.insert`. The sentence should just say something like:
We use `list.insert` to make sure the progress bar handler is run
before any other handlers, since the upload handlers are processed in
order.
--
Comment:
Thank you Baptiste, I see the oddity in the phrasing, though I also
understand Tim's point that the sentence is trying to say "do not use
append here even if you are tempted to do so".
Accepting since this could be better phrased, my proposal (as a starting
point):
> Using `list.insert()`, as shown above, ensures that the progress bar
handler is placed at the beginning of the list. Since upload handlers are
executed in order, this placement guarantees that the progress bar handler
runs before the default handlers, allowing it to track progress across the
entire upload.
--
Ticket URL: <https://code.djangoproject.com/ticket/36587#comment:2>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to django-updates+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019905f463fe-d13f4897-79fe-471b-ad41-dd58d6e4a128-000000%40eu-central-1.amazonses.com.
