argparse.HelpFormatter color argument removed in 3.15.0a3 without deprecation

[hroncok]

Bug report

Bug description:

As reported in #142274 (comment) I belive the chnage introduced an unintended API break:

Python 3.14.2 (main, Dec  5 2025, 00:00:00) [GCC 15.2.1 20251111 (Red Hat 15.2.1-4)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import argparse
>>> argparse.HelpFormatter(prog='', color=True)
<argparse.HelpFormatter object at 0x7fd998cd1400>

Python 3.15.0a3 (main, Dec 16 2025, 00:00:00) [GCC 15.2.1 20251211 (Red Hat 15.2.1-5)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import argparse
>>> argparse.HelpFormatter(prog='', color=True)
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    argparse.HelpFormatter(prog='', color=True)
    ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^
TypeError: HelpFormatter.__init__() got an unexpected keyword argument 'color'

In particular, this breaks pypa/build before pypa/build#962 -- but it can break other users as well. I believe we cannot simply remove the argument without making it a breaking change.

CPython versions tested on:

3.15

Operating systems tested on:

Linux

Linked PRs

• GH-142928: Add deprecation warning for removal of color on HelpFormatter #142946

[savannahostrowski]

Thanks for the report! Ah yeah, you're right, we should warn about this.

The color parameter on HelpFormatter was never documented and didn't work correctly when users also set color on the parser (see #139862), so it needed to be removed. However, I should have added a deprecation warning rather than removing it outright. I've opened a PR: #142928

[hugovk]

The color parameter on HelpFormatter was never documented

More to the point, HelpFormatter itself was never documented, so we could just remove the parameter, but a depreciation is fine.

[hroncok]

HelpFormatter itself was never documented, so we could just remove the parameter

FWIW I don't agree that undocumented means no backwards compatibility guarantees. https://peps.python.org/pep-0387/#backwards-compatibility-rules explicitly says "Anything documented publicly as being private" is excluded, not "Anything not documented".

EDIT: The class in question is actually documented as being private other than the name.

[mpkocher]

More to the point, HelpFormatter itself was never documented, so we could just remove the parameter, but a depreciation is fine.

I believe these API changes also need to be kept in sync with typeshed.

https://github.com/python/typeshed/blob/main/stdlib/argparse.pyi

[picnixz]

AFAIR, the formatter classes have a docstring saying that only the name of the class is public. So instantiating formatters was never part of the public API.

[hroncok]

You are right and I was wrong. Mea culpa.

Considering I found this by a real failure, I still think the depreciation warning is benefitial to have either way.

[picnixz]

Personally there are some arguments I would love to be officially supported such as the max help position etc, that is, at least the signature to be documented.

It does not make much sense to have default values otherwise.. and so I would also think a warning should be emitted for "color".

[savannahostrowski]

I discussed this more in depth with @hugovk, and after stewing on this a bit more, I don't think it's worth going through the full deprecation cycle to sidestep fundamentally broken behaviour and am inclined to close the PR I opened earlier this morning. Again, this was never documented and never worked - passing the parameter on HelpFormatter was broken from the get go. This change in behaviour is actually exposing buggy user code.