Title: Make the API of argparse.HelpFormatter public
Type: enhancement Stage:
Components: Library (Lib) Versions: Python 3.8
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 2018-01-09 07:11 by paul.j3.

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: RawDescriptionHelpFormatter removes blank lines and request a formatter that (partly) wraps lines but keeps newlines. costumize usage 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


those are all 'private' methods.
Date User Action Args
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