Command Options¶

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 occurring 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 mutually 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.

--enable¶

Enable <resource> (default)

--disable¶

Disable <resource>

enable_group = parser.add_mutually_exclusive_group()
enable_group.add_argument(
    '--enable',
    action='store_true',
    help=_('Enable <resource> (default)'),
)
enable_group.add_argument(
    '--disable',
    action='store_true',
    help=_('Disable <resource>'),
)

# This leaves 'enabled' undefined if neither option is present
if parsed_args.enable:
    kwargs['enabled'] = True
if parsed_args.disable:
    kwargs['enabled'] = False

Options with Choices¶

Some options have a specific set of values (or choices) that are valid. These choices may be validated by the CLI. If the underlying API is stable and the list of choices are unlikely to change then the CLI may validate the choices. Otherwise, the CLI must defer validation of the choices to the API. If the option has a default choice then it must be documented.

Having the CLI validate choices will be faster and may provide a better error message for the user if an invalid choice is specified (for example: argument --test: invalid choice: 'choice4' (choose from 'choice1', 'choice2', 'choice3')). The trade-off is that CLI changes are required in order to take advantage of new choices.

choice_option.add_argument(
    '--test',
    metavar='<test>',
    choices=['choice1', 'choice2', 'choice3'],
    help=_('Test type (choice1, choice2 or choice3)'),
)

Options with Multiple Values¶

Some options can be repeated to build a collection of values for a property. Adding a value to the collection must be provided via the set action. Removing a value from the collection must be provided via an unset action. As a convenience, removing all values from the collection may be provided via a --no option on the set action and a --all option on unset action. If both --no option and option are specified, the values specified on the command would overwrite the collection property instead of appending on the set action. The --all option must be part of a mutually exclusive group with the related property option on the unset action, overwrite case don’t exist in unset action.

An example behavior for set action:

Append:

object set --example-property xxx

Overwrite:

object set --no-example-property --example-property xxx

The example below assumes a property that contains a list of unique values. However, this example can also be applied to other collections using the appropriate parser action and action implementation (e.g. a dict of key/value pairs). Implementations will vary depending on how the REST API handles adding/removing values to/from the collection and whether or not duplicate values are allowed.

parser.add_argument(
    '--no-example-property',
    dest='no_example_property',
    action='store_true',
    help=_('Remove all example properties for this <resource> '
           '(specify both --no-example-property and --example-property'
           ' to remove the current properties before setting'
           ' new properties.)'),
)
parser.add_argument(
    '--example-property',
    metavar='<example-property>',
    dest='example_property',
    action='append',
    help=_('Example property for this <resource> '
           '(repeat option to set multiple properties)'),
)

if parsed_args.no_example_property and parsed_args.example_property:
    kwargs['example_property'] = parsed_args.example_property
elif parsed_args.no_example_property:
    kwargs['example_property'] = []
elif parsed_args.example_property:
    kwargs['example_property'] = \
        resource_example_property + parsed_args.example_property

example_property_group = parser.add_mutually_exclusive_group()
example_property_group.add_argument(
    '--example-property',
    metavar='<example-property>',
    dest='example_property',
    action='append',
    help=_('Example property for this <resource> '
           '(repeat option to remove multiple properties)'),
)
example_property_group.add_argument(
    '--all-example-property',
    dest='all_example_property',
    action='store_true',
    help=_('Remove all example properties for this <resource>'),
)

if parsed_args.example_property:
    kwargs['example_property'] = \
        list(set(resource_example_property) - \
             set(parsed_args.example_property))
if parsed_args.all_example_property:
    kwargs['example_property'] = []

Required Options¶

Some options have no default value and the API does not allow them to be None, then these options are always required when users use the command to which these options belong.

Required options must be validated by the CLI to avoid omissions. The CLI validation may provide an error message for the user if a required option is not specified. (for example: error: argument --test is required)

--test¶

Test option (required)

parser.add_argument(
    '--test',
    metavar='<test>',
    required=True,
    help=_('Test option (required)'),
)

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.

--long¶

List additional fields in output

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.

--marker <resource>¶

Anchor for paging (name or ID)

--limit <num-resources>¶

Limit number of <resource> returned (integer)

parser.add_argument(
    "--marker",
    metavar="<resource>",
    help="Anchor for paging (name or ID)",
)

parser.add_argument(
    "--limit",
    metavar="<num-resources>",
    type=int,
    help="Limit the number of <resource> returned",
)