argparse: customizable help formatter

[monkeyman79]

BPO	42966
Nosy	@rhettinger, @monkeyman79
PRs	bpo-42966: argparse: customizable help formatter #24377
Files	CustomizableHelpFormatter.txt

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-01-19.14:27:00.579>
labels = ['type-feature', 'library', '3.10']
title = 'argparse: customizable help formatter'
updated_at = <Date 2021-01-29.21:27:53.846>
user = 'https://github.com/monkeyman79'

bugs.python.org fields:

activity = <Date 2021-01-29.21:27:53.846>
actor = 'monkeyman79'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2021-01-19.14:27:00.579>
creator = 'monkeyman79'
dependencies = []
files = ['49750']
hgrepos = []
issue_num = 42966
keywords = ['patch']
message_count = 3.0
messages = ['385263', '385509', '385942']
nosy_count = 3.0
nosy_names = ['rhettinger', 'paul.j3', 'monkeyman79']
pr_nums = ['24377']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue42966'
versions = ['Python 3.10']

[monkeyman79]

Current implementation of the argparse module doesn't make it easy for developers to customize the help text message format. On one hand the module doesn't provide any builtin ways to do it, and the only way is to provide developer's own formatter class, on the other hand developers are threatened, that all internal structures of the module, including API of the HelpFormatter class is subject to change. Trying to customize anything but the most basic things, developer risks that his or hers module will suddenly stop working with a new version of argparse.

For most basic customization there is a set of four alternative formatting classes, but their usage as well as development of additional formatting classes is hindered by following reasons:

• Only one formatting class can be used at a time. Although arguably devloper can safely derive his own formatter class from multiple argparse's formatters - if he or she will come up with this idea.
• At this moment there is no way to pass any configuration data to the formatter object, so each formatter class can only change one aspect of the output format.
• Any new functionality added to argparse help formatting has to take form of new formatter class. If it is significant change, it means duplicating parts of HelpFormatter code and in the future maintaining additional classes.
• Even if additional formatter classes are added to argparse, developers have make sure that the new class is present in the argparse used by their module - either add dependency to specific argparse version, or dynamically check for presence of the new class in argparse module.

The most important part of this enhancement request is change in argparse public API - addition of class CustomHelpFormat. Object of this class would serve as factory for CustomizableHelpFormatter objects and could be passed to ArgumentParser constructor in place of format class type:

custom_format = argparse.CustomHelpFormat()
custom_format.indent_increment = 4
custom_format.raw_description = True
parser = argparse.ArgumentParser(formatter_class=custom_format)

The idea of passing callable instead of class type as formatter_class argument is not new, but this time it would be part of official API with access to internal details and maintained along with the module.

In conrtast to the list of drawbacks above, the advantages of this solution are:

• It is much easier to do basic customization. Developers won't have to search the internet for information how to customize argparse output, when they just want to focus on their own application functionality.
• There is no need to check for presence of future additional help formatter in the argparse module. One just has to set appropriate attribute in the 'custom_format' object. If required functionality is not present in the module on the system, it would be simply ignored, developer could even safely set attribute for future feature not present in released version.
• Detection of implemented feature would is much easier - developer would just call hasattr(custom_format, "hybrid_text_formatter") and modify displayed text accordingly in the absence of the requested feature.
• Development of new features should be easier - instead of creating new class for each possible aspect of customization, new features could be combined in one new class, or even added to the base HelpFormatter and just enabled by an attribute.

Altough this solution will not immediately help developers wanting to customize their argparse, the main idea is that it will unclog development of new formatters and incorporating existing propositions and possibly lessen or remove the need for client side customizations.

Initially, the new class would contain attributes corresponding to funcionality of existing alternative formatting classes as well as arguments to default HelpFormatter - indent, max help position and width.

Attached implementation of the CustomizableHelpFormatter class may seem rudimentary or hackish (or maybe not). Perhaps it should implement all appropriate methods instead of patching self.

[paulj3]

Years ago I proposed a format_wrapper, a Format class factory

https://bugs.python.org/issue12806#msg218395

also

https://bugs.python.org/issue39809

There I show that the formatter may be lambda

    formatter = lambda prog: argparse.HelpFormatter(prog, width=100)

The need for improving help customization has been around for a long time:

https://bugs.python.org/issue11695
Improve argparse usage/help customization

https://bugs.python.org/issue32123
Make the API of argparse.HelpFormatter public

[monkeyman79]

This is just repackaging old ideas into nice box. Instead of creating lambdas or generator function for each particular case, there is one easy to use, universal class. It will be finally written in official documentation how to change indentation.