[Django] #36587: Incorrect sentence in documentation about upload handlers

[Django]

#36587: Incorrect sentence in documentation about upload handlers
-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Type: Bug
Status: new | Component:
| Documentation
Version: 5.2 | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/36587>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#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: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

-----------------------------------+--------------------------------------
Comment (by Tim Graham):

I wouldn't say it's incorrect. I think the meaning is that "[In this
hypothetical example,] you'd probably want to [and this example does]
use..." but if you found it confusing, perhaps it's fine to change. I'd
try to avoid "We" since that's not really the documentation's style.
--
Ticket URL: <https://code.djangoproject.com/ticket/36587#comment:1>

[Django]

#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>