Open 167ea586-216e-4ac4-a3cf-b7b37ad7a4b1 opened 3 years ago
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:
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:
hasattr(custom_format, "hybrid_text_formatter")
and modify displayed text accordingly in the absence of the requested feature.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.
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
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.
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: ```python assignee = None closed_at = None created_at =
labels = ['type-feature', 'library', '3.10']
title = 'argparse: customizable help formatter'
updated_at =
user = 'https://github.com/monkeyman79'
```
bugs.python.org fields:
```python
activity =
actor = 'monkeyman79'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation =
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']
```