Skip to content

argparse.HelpFormatter color argument removed in 3.15.0a3 without deprecation #142928

Closed
Closed
argparse.HelpFormatter color argument removed in 3.15.0a3 without deprecation#142928
Assignees
savannahostrowski
Labels
3.15bugs and security fixespendingThe issue will be closed if no feedback is providedstdlibStandard Library Python modules in the Lib/ directorytype-bugAn unexpected behavior, bug, or error

Description

@hroncok
hroncok
opened on Dec 18, 2025

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

Activity

  1. hroncok
    added
    type-bugAn unexpected behavior, bug, or error
    on Dec 18, 2025
  2. aisk
    added
    stdlibStandard Library Python modules in the Lib/ directory
    3.15bugs and security fixes
    on Dec 18, 2025
  3. aisk
    added this to Argparse issueson Dec 18, 2025
  4. savannahostrowski
    self-assigned this
    on Dec 18, 2025

  5. savannahostrowski commented on Dec 18, 2025

    @savannahostrowski
    savannahostrowski
    on Dec 18, 2025
    Member

    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

  6. hugovk commented on Dec 18, 2025

    @hugovk
    hugovk
    on Dec 18, 2025
    Member

    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.

  7. hroncok commented on Dec 18, 2025

    @hroncok
    hroncok
    on Dec 18, 2025
    ContributorAuthor

    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.

  8. mpkocher commented on Dec 18, 2025

    @mpkocher
    mpkocher
    on Dec 18, 2025
    Contributor

    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

  9. picnixz commented on Dec 18, 2025

    @picnixz
    picnixz
    on Dec 18, 2025
    Member

    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.

  10. hroncok commented on Dec 18, 2025

    @hroncok
    hroncok
    on Dec 18, 2025
    ContributorAuthor

    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.

  11. picnixz commented on Dec 18, 2025

    @picnixz
    picnixz
    on Dec 18, 2025
    Member

    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".

  12. savannahostrowski commented on Dec 18, 2025

    @savannahostrowski
    savannahostrowski
    on Dec 18, 2025
    Member

    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.

  13. savannahostrowski
    added
    pendingThe issue will be closed if no feedback is provided
    on Dec 18, 2025
  14. savannahostrowski
    closed this as completedon Jan 23, 2026
  15. github-project-automation
    moved this to Doc issues in Argparse issueson Jan 23, 2026
  16. savannahostrowski
    reopened this on Jan 23, 2026
  17. savannahostrowski
    closed this as completedon Jan 23, 2026

  18. ngoldbaum commented on May 19, 2026

    @ngoldbaum
    ngoldbaum
    on May 19, 2026
    Contributor

    Not sure if it changes the calculus on this, but I ran into breakage related this over in build on Python 3.15, see pypa/build#1067.

    EDIT: never mind, this has already been fixed in build.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

3.15bugs and security fixespendingThe issue will be closed if no feedback is providedstdlibStandard Library Python modules in the Lib/ directorytype-bugAn unexpected behavior, bug, or error

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions