Repository navigation
argparse.HelpFormatter color argument removed in 3.15.0a3 without deprecation #142928
Description
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
Metadata
Metadata
Assignees
Labels
Projects
- Status
Activity
savannahostrowski commentedon Dec 18, 2025
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 commentedon Dec 18, 2025
More to the point, HelpFormatter itself was never documented, so we could just remove the parameter, but a depreciation is fine.
hroncok commentedon Dec 18, 2025
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 commentedon Dec 18, 2025
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 commentedon Dec 18, 2025
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 commentedon Dec 18, 2025
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 commentedon Dec 18, 2025
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 commentedon Dec 18, 2025
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.
ngoldbaum commentedon May 19, 2026
Not sure if it changes the calculus on this, but I ran into breakage related this over in
buildon Python 3.15, see pypa/build#1067.EDIT: never mind, this has already been fixed in
build.