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 use argparse 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 do click is often going to be a better answer than raw optparse.
• keeps the initial note in the getopt docs
• adds an initial note to the optparse docs that goes into exactly where argparse runs into problems
• adds "See Also" links for click and Typer to the optparse docs (I left them out of the argparse docs due to the analysis paralysis concern)
• splits out a new "Command Line Implementation Libraries" chapter in the docs, with these 3 modules, getpass, and curses (I was tempted to move fileinput 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 the optparse undeprecation. I still dropped any mention of getopt 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 that optparse 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 of getopt and optparse should be reverted, and replaced with guidance on times when optparse is unequivocally the better option (because argparse doesn't work properly for those use cases)
• (the still controversial bit) the default argparse recommendation should be dropped entirely because there are some signature definitions that argparse will mishandle

There are lots of CLIs where the problem of argparse 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 that argparse handles them strangely).

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

• the solution must be in the standard library (if that isn't the case, use click or Typer instead)
• the solution must handle leading - with the more standard conventions implemented by optparse rather than the quirky behaviours exhibited by argparse

We've spent ~15 years of telling people to use argparse over optparse, 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 like click.

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

Edit: Serhiy clarified on the other PR that my assumption that mishandling leading - characters was the only problematic argparse quirk is incorrect. That does strengthen Serhiy's point that the underlying problem with argparse 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 recommend argparse even if we know about its flaws which were not fixed in past 15 years.