Misleading sentence in documentation about upload handlers

[Baptiste Mispelon]

The documentation about ​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.

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

[Natalia Bidart]

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.

[Chaitanya Keyal]

​PR

[Sarah Boyce <42296566+sarahboyce@…>]

In afe6634:

Fixed #36587 -- Clarified usage of list.insert() for upload handlers.

Thanks Baptiste Mispelon for the report

Co-authored-by: Natalia <124304+nessita@…>

[Sarah Boyce <42296566+sarahboyce@…>]

In 01515099:

[6.0.x] Fixed #36587 -- Clarified usage of list.insert() for upload handlers.

Thanks Baptiste Mispelon for the report

Co-authored-by: Natalia <124304+nessita@…>

Backport of afe6634146d0fe70498976c49d2eb4d745aa9064 from main.

[Sarah Boyce <42296566+sarahboyce@…>]

In 81625a1:

[5.2.x] Fixed #36587 -- Clarified usage of list.insert() for upload handlers.

Thanks Baptiste Mispelon for the report

Co-authored-by: Natalia <124304+nessita@…>

Backport of afe6634146d0fe70498976c49d2eb4d745aa9064 from main.