argparse: suggestion for formatting optional positional args

[66e7b4de-47b9-480c-978f-f7c010085270]

BPO	11708
Nosy	@pwil3058, @akheron
Files	regroup.patch test_regroup.py

^{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.11'] title = 'argparse: suggestion for formatting optional positional args' updated_at = user = 'https://github.com/pwil3058' ``` bugs.python.org fields: ```python activity = actor = 'iritkatriel' assignee = 'none' closed = False closed_date = None closer = None components = ['Library (Lib)'] creation = creator = 'pwil3058' dependencies = [] files = ['35034', '35035'] hgrepos = [] issue_num = 11708 keywords = ['patch'] message_count = 6.0 messages = ['132462', '141050', '149543', '198038', '217153', '217154'] nosy_count = 4.0 nosy_names = ['bethard', 'pwil3058', 'petri.lehtinen', 'paul.j3'] pr_nums = [] priority = 'normal' resolution = None stage = 'needs patch' status = 'open' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue11708' versions = ['Python 3.11'] ```

[66e7b4de-47b9-480c-978f-f7c010085270]

At present, if a number (e.g. 2) of optional positional arguments are defined (e.g. arg1 and arg2) argparse formats them as follows:

usage: program [arg1] [arg2]

in the usage message. I would like to suggest that a better format would be:

usage: program [arg1 [arg2]]

as this more accurately reflects the way argparse treats them during parsing of the command line.

This formatting would be consistent with the way argparse currently formats a single optional positional argument with nargs='*', namely:

usage: program [arg [arg ...]]

[akheron]

I think this is a good idea, and seems to me more like a bug than a feature request.

[8955c213-fd54-471c-9758-9cc5f49074db]

I agree that this is a bug in current argparse formatting.

It might be a little difficult to fix though because the current option formatting handles arguments one at a time, and producing something like [arg1 [arg2]] requires some understanding of how arguments interact, which the formatter currently doesn't have.

But patches are certainly welcome.

[7a064fe6-c535-4d80-a11f-a04ed39056c5]

This is a HelpFormatter function that takes a list of formatted actions, and groups contiguous blocks of optional positional actions. It accounts for optionals (via prefix_chars) and mutually exclusive groups.

Since it assumes 'parts' is a list, rather than string, it works best with the '_format_actions_usage' method in the patch that I submitted to http://bugs.python.org/issue11874

    def _positionals_regroup(self, parts):
        # change '[arg1] [arg2]' to '[arg1 [arg2]]'
        # apply to a list of formatted arguments
        # don't apply to optionals (with prefix chars) or groups
        chars = getattr(self, 'prefix_chars',set('-'))
        R = _re.compile(r'\] \[(.*)\]')
        result = []
        text = None
        while  parts:
            part = parts.pop()
            if part:
                if part[0]=='[' and part[1] not in chars and '|' not in part:
                    if text:
                        text = ' '.join([part, text])
                    else:
                        text = part
                    if R.search(text):
                        text = R.sub(' [\g<1>]]',text)
                else:
                    if text:
                        result.insert(0,text)
                        text = None
                    result.insert(0,part)
        if text:
            result.insert(0,text)
        return result

To avoid compatibility issues it could implemented in a subclassed HelpFormatter.

[7a064fe6-c535-4d80-a11f-a04ed39056c5]

This patch adds a ReGroupHelpFormatter class, which regroups positional arguments in the usage line as discussed before. It builds on the reworked usage formatter in bugs/python.org/issue11874 (which keeps usage as a list longer).

For a complicate parser, usage may look like:

usage: regp [-h] foo [arg1 [arg2 [arg3 [arg3 ...] [arg4]]]]

[7a064fe6-c535-4d80-a11f-a04ed39056c5]

This is a testing script for this patch. It is not a unit test. Example:

    p = argparse.ArgumentParser()
    p.formatter_class = argparse.ReGroupHelpFormatter
    p.add_argument('foo')
    p.add_argument('arg1',nargs='?')
    p.add_argument('arg2',nargs='?')
    a = p.add_argument('arg3',nargs='*')
    b = p.add_argument('arg4', nargs='?')
    # usage: regp [-h] foo [arg1 [arg2 [arg3 [arg3 ...] [arg4]]]]

[serhiy-storchaka]

This is an interesting feature. I do not think that it should be a separate class, fine details of the main formatter were already changed several times.

@hpaulj are you interesting in creating a PR? I would be happy to review and merge other your patches.

Please test also cases when the last positional argument or several last positional arguments are required (nargs is None or an integer).

[hpaulj]

Sorry, my current usage of the python github is too limited to create a PR. I'm just using a miniconda distribution of python. PaulJ

On Sat, Sep 28, 2024, 3:33 AM Serhiy Storchaka @.***> wrote:

This is an interesting feature. I do not think that it should be a separate class, fine details of the main formatter were already changed several times.

@hpaulj https://github.com/hpaulj are you interesting in creating a PR? I would be happy to review and merge other your patches.

Please test also cases when the last positional argument or several last positional arguments are required (nargs is None or an integer).

— Reply to this email directly, view it on GitHub https://github.com/python/cpython/issues/55917#issuecomment-2380596777, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAITB6GUSBXLYC4WU6LPO4DZY2AXJAVCNFSM6AAAAABPAQH34GVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOBQGU4TMNZXG4 . You are receiving this because you were mentioned.Message ID: @.***>