#50281 CLI positional arguments should be listed first in the usage section
Opened a year ago by spichugi. Modified 5 months ago

Issue Description

CLI commands are sensitive to the position of arguments. argparse ignores the fact while auto-generating the usage section. We should fix it with a custom formatter so our customers won't be confused.

It may help:
https://stackoverflow.com/questions/26985650/argparse-do-not-catch-positional-arguments-with-nargs/26986546#26986546

Steps to reproduce

  1. dsconf -v ldapi://%2fvar%2frun%2fslapd-local3.socket plugin attr-uniq add -h

Actual results

usage: dsconf instance plugin attr-uniq add [-h]
                                        [--attr-name ATTR_NAME [ATTR_NAME ...]]
                                        [--subtree SUBTREE [SUBTREE ...]]
                                        [--across-all-subtrees {on,off}]
                                        [--top-entry-oc TOP_ENTRY_OC]
                                        [--subtree-entries-oc SUBTREE_ENTRIES_OC]
                                        NAME

Expected results

usage: dsconf instance plugin attr-uniq add [-h]
                                        NAME
                                        [--attr-name ATTR_NAME [ATTR_NAME ...]]
                                        [--subtree SUBTREE [SUBTREE ...]]
                                        [--across-all-subtrees {on,off}]
                                        [--top-entry-oc TOP_ENTRY_OC]
                                        [--subtree-entries-oc SUBTREE_ENTRIES_OC]

Is this because we have nargs='?' in the cli in question?

Metadata Update from @firstyear:
- Custom field origin adjusted to None
- Custom field reviewstatus adjusted to None

a year ago

Is this because we have nargs='?' in the cli in question?

It is not related to nargs. It is just how argparse works. First it mentions all optional arguments and only after this it lists the positional arguments.
So it is misleading and also our CLI tools will fail if you specify positional argument after optional arguments (it is how we define them in the code)

If they are failing in this context, then that indicates an arg parse bug perhaps?

Could it be because --subtree and --attr-name are nargs='+'?

Could it be because --subtree and --attr-name are nargs='+'?

Yeah, actually, it looks like this. My bad.

But anyway, I think the help will be more helpful if it will list DN first.

I've just heard about the issue a couple of times from different persons who tested CLI... We can help our future customers to avoid the obstacles as much as possible.

Honestly, I think this is a bug in argparse if this is happening. IMO --subtree with nargs should be --subtree 1 --subtree 2 --subtree 3, not "--subtree 1 2 3", because then we don't know where it ends ....

Honestly, I think this is a bug in argparse if this is happening. IMO --subtree with nargs should be --subtree 1 --subtree 2 --subtree 3, not "--subtree 1 2 3", because then we don't know where it ends ....

Looks to me, that it is just a way they designed it intentionally... (this understanding I got from their issues in a bug tracker and from their docs)

If you think it is a bug from their side, could you please open an issue on their tracker with your idea?
Then, if they'll reply negatively, we can continue on the HelpFormatter here... If they reply positively, we'll close this issue.

What do you think?

Can you link the issues and docs you refer to here?

I think the helpformatter is a good idea anyway, we can approach it from both sides :)

Can you link the issues and docs you refer to here?

I was generally going through the list and reading comments there, sometimes following links to docs - https://bugs.python.org/issue?%40columns=id%2Cactivity%2Ctitle%2Ccreator%2Cassignee%2Cstatus%2Ctype&%40sort=-activity&%40filter=status&%40action=searchid&ignore=file%3Acontent&%40search_text=argparse+positional&submit=search&status=-1%2C1%2C2%2C3

I think the helpformatter is a good idea anyway, we can approach it from both sides :)

https://bugs.python.org/issue9338
THis looks exactly like our issue :)

Sure. Though my thought "Looks to me, that it is just a way they designed it intentionally..." was about your proposal for "--subtree 1 --subtree 2 --subtree 3". I don't think that they will allow that. But we can try to push it...

Regarding the issue, you linked... Yeah, it is the same issue we have but it looks like they do nothing about it... And the common workaround is - just specify the order (while calling your command) in the way that positional arguments don't mess the args=+.

So in that case, I think, the HelperFormatter may be the only real solution for us that we can get here soon.

Metadata Update from @mreynolds:
- Issue set to the milestone: 1.4.1

a year ago

Metadata Update from @mreynolds:
- Issue priority set to: minor
- Issue set to the milestone: 1.4.4 (was: 1.4.1)

5 months ago

Login to comment on this ticket.

Metadata