diff --git a/doc/source/command-options.rst b/doc/source/command-options.rst new file mode 100644 index 0000000000..edafb15322 --- /dev/null +++ b/doc/source/command-options.rst @@ -0,0 +1,135 @@ +=============== +Command Options +=============== + +OpenStackClient commands all have a set of zero or more options unique to +the command, however there are of course ways in which these options are +common and consistent across all of the commands that include them. + +These are the set of guidelines for OSC developers that help keep the +interface and commands consistent. + +In some cases (like the boolean variables below) we use the same pattern +for defining and using options in all situations. The alternative of only +using it when necessary leads to errors when copy-n-paste is used for a +new command without understanding why or why not that instance is correct. + +Boolean Options +=============== + +Boolean options for any command that sets a resource state, such as 'enabled' +or 'public', shall always have both positive and negative options defined. +The names of those options shall either be a naturally occuring pair of +words (in English) or a positive option and a negative option with `no-` +prepended (such as in the traditional GNU option usage) like `--share` and +`--no-share`. + +In order to handle those APIs that behave differently when a field is set to +`None` and when the field is not present in a passed argument list or dict, +each of the boolean options shall set its own variable to `True` as part of +a mutiually exclusive group, rather than the more common configuration of setting a +single destination variable `True` or `False` directly. This allows us to +detect the situation when neither option is present (both variables will be +`False`) and act accordingly for those APIs where this matters. + +This also requires that each of the boolean values be tested in the +`take_action()` method to correctly set (or not) the underlying API field +values. + +.. option:: --enable + + Enable (default) + +.. option:: --disable + + Disable + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this:: + +.. code-block: python + + enable_group = parser.add_mutually_exclusive_group() + enable_group.add_argument( + '--enable', + action='store_true', + help=_('Enable (default)'), + ) + enable_group.add_argument( + '--disable', + action='store_true', + help=_('Disable '), + ) + +An example handler in `take_action()`:: + + # This leaves 'enabled' undefined if neither option is present + if parsed_args.enable: + kwargs['enabled'] = True + if parsed_args.disable: + kwargs['enabled'] = False + +List Command Options +==================== + +Additional Fields +----------------- + +Most list commands only return a subset of the available fields by default. +Additional fields are available with the `--long` option. All list +commands should allow `--long` even if they return all fields by default. + +.. option:: --long + + List additional fields in output + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this:: + +.. code-block: python + + parser.add_argument( + '--long', + action='store_true', + default=False, + help='List additional fields in output', + ) + +Pagination +---------- + +There are many ways to do pagination, some OpenStack APIs support it, some don't. +OpenStackClient attempts to define a single common way to specify pagination on +the command line. + +.. option:: --marker + + Anchor for paging + +.. option:: --limit + + Limit number of returned (*integer*) + +Implementation +~~~~~~~~~~~~~~ + +The parser declaration should look like this:: + +.. code-block: python + + parser.add_argument( + "--marker", + metavar="", + help="Anchor for paging", + ) + + parser.add_argument( + "--limit", + metavar="", + type=int, + help="Limit the number of returned", + ) diff --git a/doc/source/index.rst b/doc/source/index.rst index c90b8e5296..6b7d63f36e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -37,6 +37,7 @@ Developer Documentation :maxdepth: 1 developing + command-options Project Goals -------------