I missed that@serhiy-storchaka had already started on a PR for this, so#126227 is an alternative take on the same change which goes a bit further than this one does in some respects, but not as far in others:

• retains a stronger useargparse default position to avoid triggering analysis paralysis in beginners. Yes,argparse has genuine problems (which Serhiy has been valiantly attempting to resolve), but most people won't hit them, and if they doclick is often going to be a better answer than rawoptparse.
• keeps the initial note in thegetopt docs
• adds an initial note to theoptparse docs that goes into exactly where argparse runs into problems
• adds "See Also" links forclick andTyper to theoptparse docs (I left them out of theargparse docs due to the analysis paralysis concern)
• splits out a new "Command Line Implementation Libraries" chapter in the docs, with these 3 modules,getpass, andcurses (I was tempted to movefileinput as well,but ended up leaving it alone and eventually gave in to that temptation)
• Changes the 3.13 What's New to explicitly note theoptparse undeprecation. I still dropped any mention ofgetopt at all, since this is a reversion to the 3.12 status quo where that module is concerned.

I like some of the other changes Serhiy has included here, so I'm going to include them to the other PR with a Co-Authored-By note.

I've also added the DO-NOT-MERGE label to both PRs, as I agree with@hugovk that we want to let the discussion on this play out for a while longer yet.

@serhiy-storchaka Are you cool with@ncoghlan's approach or do you want to work together to refine either one of the existing PRs?

I am fine with either option, but I think thatoptparse should not be downplayed. For now, it is the safest option for beginners.argparse is too risky.

@serhiy-storchaka Perhaps we can separate the two concerns? I think there's a piece the two of us agree on, and a piece where we still disagree (at least for now):

• (the bit I think at least the two of us agree on) the documented deprecations ofgetopt andoptparse should be reverted, and replaced with guidance on times whenoptparse is unequivocally the better option (becauseargparse doesn't work properly for those use cases)
• (the still controversial bit) the defaultargparse recommendation should be dropped entirely because there are some signature definitions thatargparse will mishandle

There arelots of CLIs where the problem ofargparse mishandling leading- characters (and any similar issues) simply won't come up, because those kinds of names don't occur in practice (e.g. very few people using leading underscores in file names, so if your only options with value parameters accept file names, it probably doesn't matter to you thatargparse handles them strangely).

While there are places where itmight make sense for people to useoptparse directly, I think it's limited to the following:

• the solutionmust be in the standard library (if that isn't the case, useclick orTyper instead)
• the solutionmust handle leading- with the more standard conventions implemented byoptparse rather than the quirky behaviours exhibited byargparse

We've spent ~15 years of telling people to useargparse overoptparse, and the GitHub code search results suggest that by and large people have either been happy with that recommendation, or else sought out third party solutions likeclick.

Itmight be reasonable to include those third party recommendations in theargparse docs (in addition to having them in theoptparse docs), but I don't think we'd be genuinely helping people by directing them to the lower leveloptparse API unless they already knew what they were doing.

Edit: Serhiy clarified on the other PR that my assumption that mishandling leading- characters was theonly problematicargparse quirk is incorrect. That does strengthen Serhiy's point that the underlying problem withargparse is that when it fails, it can often be because it is behaving unreasonably, not because it is being asked to do something unreasonable, leading beginners to think they're the ones at fault, when the problem is really with argparse's behaviour being quirky.

Closing this in favor of@ncoghlan's#126227, although I disagree with continuing to recommendargparse even if we know about its flaws which were not fixed in past 15 years.