openstack team mailing list archive

[Doug Hellmann <doug.hellmann@xxxxxxxxxxxxx>]

On Mon, Apr 30, 2012 at 3:19 PM, Dolph Mathews <dolph.mathews@xxxxxxxxx>wrote:

>
>
> On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann <
> doug.hellmann@xxxxxxxxxxxxx> wrote:
>
>>
>>
>> On Mon, Apr 30, 2012 at 12:13 PM, Adam Spiers <aspiers@xxxxxxxx> wrote:
>>
>>> Dean Troyer (dtroyer@xxxxxxxxx) wrote:
>>> > One of the first things to do is to find out who is interested in
>>> > contributing to this project.and hopefully coordinating some of the
>>> > work with the other emerging project-specific clients.  Send me an
>>> > email and I'll build a list to get the discussion started.
>>>
>>> Count me in - by 'build a list' do you mean a new mailing list?
>>>
>>> I've read http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines
>>> (which looks like a great start on the topic!) and made some minor
>>> tweaks.  Should we discuss the FIXMEs you marked here or elsewhere?  I
>>> wanted to make a few suggestions before I forget - can always continue
>>> discussion elsewhere if appropriate:
>>>
>>>  1. Regarding "The subject names are always specified in command in
>>>     their singular form.  This is contrary to natural language use."
>>>
>>>       - I didn't understand the second sentence here, but shouldn't the
>>>         HIG should allow for scenarios where the verb can operate both on
>>>         individual objects and on multiple objects in batch?
>>>
>>
>> I read that as meaning the command to list instances available to a
>> tenant should be "list server" not the more natural "list servers".
>>
>
> I really hope that "list servers" would work.
>

I tend to agree, I was just explaining how I interpreted what was there.


>
>
>>
>> Can you give an example of a command that would work on multiple objects
>> in batch?
>>
>>
>>>
>>>     (Grammatical nitpick: if the verb is acting on the noun, then the
>>>     HIG should refer to the noun as "object" rather than "subject".)
>>>
>>>  2. I think it would be good if the HIG gave guidelines on how the
>>>     command should behave when run with no arguments.
>>>
>>
>> Running a cliff-based app without any arguments enters "interactive" mode
>> (as of 0.4) which gives the user a new prompt and lets them run multiple
>> commands before exiting. This is intended to be used as an optimization for
>> commands to cache authentication credentials and clients and avoid logging
>> in for every sub-command.
>>
>
> One solution for this today is to use keystone's existing "token_get"
> command, and then run subsequent commands with your specified token. So,
> it's basically one request per command, instead of complete auth + request
> per command.
>
>     $ keystone token-get
>     $ keystone --token=$TOKEN --endpoint=$ENDPOINT tenant-create [...]
>

That sounds sort of like the way ssh-agent works, and I like that as an
optimization, too.


> Since we're using argparse for the subcommands, the default behavior if a
>> command is run without arguments depends on the subcommand. If the
>> subcommand has no required arguments, it will do whatever it is meant to
>> do. If it does require arguments and sees none, argparse prints an error
>> message about whatever is missing (and possibly suggests that the user use
>> --help to get instructions).
>>
>>
>>>
>>>  3. I think it would be good if the HIG recommended that, at least
>>>     when subcommands are permitted, single arguments '--help' and
>>>     'help' always generate identical output:
>>>
>>>       https://bugs.launchpad.net/keystone/+bug/936399
>>>       https://review.openstack.org/#/c/6460/
>>
>>
>> The current version of cliff eats the --help option no matter where it
>> appears on the command line, so to get help on a subcommand you always have
>> to use "help" (without the dashes).
>>
>> $ openstack --help
>> $ openstack list server --help
>>
>> both print the help for the "openstack" command, including a list of
>> available subcommands
>>
>>  $ openstack help list server
>>
>> prints the help for the "list server" subcommand of "openstack"
>>
>
> I find this behavior really annoying... --help should be contextual
> (depending on whether a subcommand is present, and what it is).
>

That's how it worked originally. When I got the pull-request from Dean I
assumed it was intended to follow some existing standard.

>From an implementation perspective, it was challenging to use two levels of
argparse parsers to have the --help option applied separately, so I had the
main app using optparse configured to stop at the first positional argument
(value without a "-" at the front). That was a little ugly, since it
depended on a deprecated module. I was not able to find a way to do exactly
the same thing in argparse without adding some of my own logic on top.


>  4. I think it would be good if the HIG gave guidelines on how the
>>>     help text should be formatted - in particular that positional
>>>     arguments are covered by the help text (e.g. keystone-manage does
>>>     not currently give any info on positional arguments required
>>>     until you specify too few).
>>>
>>
>> Do we need to specify this beyond saying that all subcommands must use
>> argparse for argument parsing (the new framework depends on it anyway, and
>> then they are all consistent)?
>>
>
> I hope not... +1 for argparse.
>
>
>>
>>
>>>
>>>  5. I think it would be good if the HIG specified what sort of help
>>>     text should be included alongside error messages of (say) the
>>>     "you didn't give the right number of arguments" variety, and
>>>     whether the error message should appear before or after that help
>>>     text.  My vote is after, because it's far easier for the human
>>>     eye to locate the end of a command's output than the beginning,
>>>     especially if the beginning has scrolled off the top of the
>>>     terminal.
>>
>>
>>> Thanks,
>>> Adam
>>>
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~openstack
>>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~openstack
>>> More help   : https://help.launchpad.net/ListHelp
>>>
>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>>
>>
>