This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Make the API of argparse.HelpFormatter public
Type: enhancement Stage:
Components: Library (Lib) Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: Bernhard10, paul.j3, terry.reedy
Priority: normal Keywords:

Created on 2017-11-24 09:53 by Bernhard10, last changed 2022-04-11 14:58 by admin.

Messages (4)
msg306879 - (view) Author: Bernhard10 (Bernhard10) Date: 2017-11-24 09:53
Since there have not been any significant change to the code of argparse.HelpFormatter in the last few years but there are still some open issues where people want to customize formatting, I would like to ask: What is required before parts of the API of argparse.HelpFormatter can be made public?

Related issues:
https://bugs.python.org/issue17113 RawDescriptionHelpFormatter removes blank lines
https://bugs.python.org/issue12806 and https://bugs.python.org/issue22029 request a formatter that (partly) wraps lines but keeps newlines.
https://bugs.python.org/issue11695 costumize usage
https://bugs.python.org/issue28742 Improve ArgumentDefaultsHelpFormatter


All this issues could be fixed outside the standard library by sub-classing HelpFormatter, which would require a public and documented API for it.

So my question: What is missing before HelpFormatter can get a public API and how can I help?
msg306926 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-11-24 22:06
I suggest that you open a thread on python-ideas list: something like 'Make argparse.HelpFormatter public'.  Explain what you would like to have happen and why.
msg307761 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2017-12-06 18:21
A difficulty with writing a public API is that useful changes can occur at almost any level of the class.

The existing subclasses modify small, but deep methods, ones that handle things like line wrapping.

On the other hand, most of the issues you cite deal with higher level issues, either the top most method of the formatter, or alternatives to parser.format_help or parser._get_formatter (which create and populate a formatter object).

I've also responded to issues dealing with intermediate levels things, like the need for a more robust usage formatting, and changing how help lines are constructed.

The argparse documentation is a mix of how-to and formal API.  Mostly it describes how to perform common parsing tasks.  Even though argparse consists of classes, the documentation does not formally describe the classes, and their subclassing and all methods.  It's not a reference API.
msg309687 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2018-01-09 07:11
To elaborate on my last comment, the existing subclasses that customize formatting modify

_fill_text
_split_lines
_get_help_string
_get_default_metavar_for_optional
_get_default_metavar_for_positional

those are all 'private' methods.
History
Date User Action Args
2022-04-11 14:58:54adminsetgithub: 76304
2018-01-09 07:11:00paul.j3setmessages: + msg309687
2017-12-06 18:21:37paul.j3setnosy: + paul.j3
messages: + msg307761
2017-11-24 22:06:57terry.reedysetnosy: + terry.reedy
messages: + msg306926
2017-11-24 09:53:23Bernhard10create