gh-92248: Deprecate type, choices, metavar parameters of argparse.BooleanOptionalAction

[sobolevn]

argparse.BooleanOptionalAction was added in 3.9
#85039 removed just a single wrong parameter.
But, it was on time when 3.9 was recently released, and no deprecation warning was issued.
The parameter was just removed.

But, since we already have 3.9, 3.10, and 3.11, (and all alphas of 3.12), I am sure that we need a deprecation period now.

People might use this (the use-case is probably wrong), but I don't like breaking things for no clear benefit.

I'm feeling pretty safe about this deprecation (I even considered just removing these parameters straight away), because code search shows that no one is using these arguments: https://cs.github.com/?q=action%3DBooleanOptionalAction

Plus, they don't make any sense and are mostly not changing any behaviour of BooleanOptionalAction.

CC @barneygale since you've asked for this 😆
CC @rhettinger and @hauntsaninja since you've reviewed #85039

• Issue: argparse.BooleanOptionalAction accepts and silently discards choices, metavar, and type arguments #92248

[rhettinger]

This would gradually nudge the code toward the way it should have been designed from the outset. Eventually, it might save someone a few minutes of time.

That said, this is a pretty minor issue (ignoring unused arguments). Changing the behavior will be inconvenient for people who happened to have fed in an unused argument in code that is currently functioning correctly — we've breaking code that was sloppy but correct — I'm not sure they will appreciate being forced to make a minor edit that doesn't change behavior or fix any problem that they have.

[sobolevn]

@rhettinger thank you for your input. However, I don't quite agree with some of your points.

Changing the behavior will be inconvenient for people who happened to have fed in an unused argument in code that is currently functioning correctly

Two things here:

1. Changing the behavior will be inconvenient: Yes, it can cause a new warning. But, this is pretty easy to deal with: just remove the argument. It won't require any compat code or migration plan. I think that this is a good thing, because it helps to indicate a problem with your code. And, of course, people with the correct code won't have any warnings at all
2. currently functioning correctly: I don't think that we can call this code "correct". Here's the first example:

>>> from argparse import *
>>> parser = ArgumentParser()
>>> parser.add_argument('--foo', action=BooleanOptionalAction, type=int)  # we expect `int`
>>> parser.parse_args(['--foo'])  # but get `bool`
Namespace(foo=True)

Here's the code does not "function correctly" in a sense that type is ignored. While user explicitly asks to use int.

The second example:

>>> from argparse import *
>>> parser = ArgumentParser()
>>> parser.add_argument('--foo', action=BooleanOptionalAction, choices=['on', 'off'])
>>> parser.parse_args(['--foo'])
Namespace(foo=True)

And again: user specifies two values that must be respected. But, they are ignored.

We also do not document this behaviour:

So, any user might expect it to work similarly to other action types. Which is not the case right now.

All in all, I see this as an improvement:

1. We show what's wrong and do not break any code
2. In the future we will have the correct signature that does the correct thing

[hugovk]

Let's merge this before the beta if there's no remaining objections.