Closed kotfu closed 1 year ago
Questions:
Are these behaviors with [brackets|braces|commas|pipes] intentional?
Yes. I don't do any highlighting for these characters because I don't think highlighting them helps make the CLI help text clearer and easier to read by a human -- this is kinda the whole reason I created this project.
If not, would you consider rendering all of these symbols (braces, brackets, commas, pipes) with a new style, perhaps something like "argparse.symbols"?
If by "all of these symbols" you mean all of your four bullet point examples above then the simple answer is no, I would not consider it. The ones that are colored now (examples 2 & 4) are part of the metavar
produced by argparse. I have no intention in parsing metavars as it is a very complicated business. It becomes even more complicated if you factor in the fact that metavars can be set by the user to technically anything. But even without taking user metavars into account, it is very difficult to get a generic solution right. As a for instance, apply this diff to your example and notice the difference in output:
parser.add_argument(
"config_name",
- nargs="?",
+ nargs="+",
help="a configuration name",
)
If you mean only the symbols that are currently not colored (examples 1 & 3), then I might consider them. I don't have the time (or interest to be frank) to implement this feature though. If you send a PR that is simple enough, well tested, and works with all the quirks of argparse's parenthesis and brackets manipulations I will accept it.
After thinking about this a bit more, I think the brackets handling within argparse usage is too fragile. Some of the upstream bugs are enumerated here https://github.com/python/cpython/pull/105039. Implementing this proposal would only lead to more errors with no real benefit compared to the effort. I am closing this now but I may reconsider it when argparse handling of usage is fixed and its semantics are clear.
Consider the following argument parser:
Note the inconsistent highlighting of brackets and braces.
-s
) that are not required are surrounded in unstyled bracketsconfig_name
) are surrounded by brackets styled withargparse.args
--rich
and--poor
are surrounded by unstyled brackets and separated by an unstyled pipe character-s
option are also mutually exclusive. They are surrounded by braces, and separated by a comma, but the braces and comma are styled withargparse.metavar
Observation: The brackets around optional arguments and the pipe separating the mutually exclusive options are the only text output which can not be styled using RichHelpFormatter.styles.
Suggestion: choices for an option (i.e.
-s
) of which you can only choose one, and mutually exclusive options (i.e.--rich
and--poor
), of which you can only choose one, should be rendered consistently.Questions: