gh-143860: Clarify argparse.parse_args argument order

[VanshAgarwal24036]

Clarify the wording for the args parameter of
ArgumentParser.parse_args() to make the processing order explicit.

No behavioral changes.

• Issue: Document argparse.ArgumentParser.parse_args order guarantee #143860

---

📚 Documentation preview 📚: https://cpython-previews--143863.org.readthedocs.build/

[VanshAgarwal24036]

@hugovk Thanks for the feedback!

Would one of the following be clearer?

1. “List of strings to parse, processed from left to right.”
2. “List of strings to parse, in the order they appear.”
3. “List of strings to parse; arguments are processed sequentially.”

Happy to update the wording to your preference.

[johnslavik]

Respectively?

[terryjreedy]

The discourse discussion was mostly about the fact that a list arg, as opposed to an iterable arg, could be processed in reverse, for instance by popping, or in any order. In the example use of argparse, the order mattered. The OP and others would like a order guarantee. This seems sensible to me.

My original suggested addition, "in normal order", meant "in normal left to right order" or equivalently, "in normal iteration order". I personally would go with the last, but Savannah can choose.

[VanshAgarwal24036]

Thanks for the clarification — that makes sense.

I’ll update the wording to explicitly state that the arguments are processed in normal iteration (left-to-right) order, to reflect the intended guarantee discussed on Discourse.

[hugovk]

I understand you want a guarantee to point to, but I'm not sure if this is really adding much to improve the docs.

Our style guide says:

More documentation is not necessarily better documentation. Err on the side of being succinct.

It is an unfortunate fact that making documentation longer can be an impediment to understanding and can result in even more ways to misread or misinterpret the text. Long descriptions full of corner cases and caveats can create the impression that a function is more complex or harder to use than it actually is.

If it's just for the benefit of the open-source project who want a guarantee, you can point them at this DPO thread, issue or PR. And it looks like they were satisfied with the DPO thread: zephyrproject-rtos/zephyr#101888 (comment).

If we really do need to clarify this (do we?), I don't think 3-4 words help much, and it should be explained in a bit more detail, perhaps with a brief example.

[VanshAgarwal24036]

Thanks for the thoughtful feedback — that’s fair.

I agree that keeping the documentation concise is important. My intent here was simply to make the ordering guarantee explicit for readers who might otherwise assume the input could be processed in an arbitrary order, as discussed on Discourse.

That said, I’m very happy to adjust or simplify the wording further (or remove it if needed) in line with the documentation style guidance — I’ll follow whatever direction you think is most appropriate here.

[savannahostrowski]

Yeah, I don't think this provides much in the way of additional clarity; iterating a list left-to-right is pretty fundamental Python behavior. My preference is to keep the argparse docs concise, since they're already quite long. Thanks for the contribution though!

[VanshAgarwal24036]

Thanks for the clarification — that makes sense.

I appreciate the review and the guidance on keeping the documentation concise. I’m happy to defer to this direction and will wait for your guidance on the next step.

[savannahostrowski]

I'd opt to close this PR (and the related issue) and just refer people to the thread on Discuss per Hugo's suggestion above.

[VanshAgarwal24036]

Thanks for the clarification and for taking the time to review this.

That makes sense — I appreciate the guidance. Happy to proceed with closing and referring interested users to the Discourse thread.