Merge "Devref: Options with Multiple Values"

1 files changed, 81 insertions, 0 deletions

diff --git a/doc/source/command-options.rst b/doc/source/command-options.rst
index b3cc002a..d47a56dc 100644
--- a/doc/source/command-options.rst
+++ b/doc/source/command-options.rst
@@ -105,6 +105,87 @@ An example parser declaration:
             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`` and ``unset`` actions. The ``--no`` option must
+be part of a mutually exclusive group with the related property option.
+
+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.
+
+Implementation
+~~~~~~~~~~~~~~
+
+An example parser declaration for `set` action:
+
+.. code-block:: python
+
+        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 set multiple properties)'),
+        )
+        example_property_group.add_argument(
+            '--no-example-property',
+            dest='no_example_property',
+            action='store_true',
+            help=_('Remove all example properties for this <resource>'),
+        )
+
+An example handler in `take_action()` for `set` action:
+
+.. code-block:: python
+
+        if parsed_args.example_property:
+            kwargs['example_property'] = \
+                resource_example_property + parsed_args.example_property
+        if parsed_args.no_example_property:
+            kwargs['example_property'] = []
+
+An example parser declaration for `unset` action:
+
+.. code-block:: python
+
+        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(
+            '--no-example-property',
+            dest='no_example_property',
+            action='store_true',
+            help=_('Remove all example properties for this <resource>'),
+        )
+
+An example handler in `take_action()` for `unset` action:
+
+.. code-block:: python
+
+        if parsed_args.example_property:
+            kwargs['example_property'] = \
+                list(set(resource_example_property) - \
+                     set(parsed_args.example_property))
+        if parsed_args.no_example_property:
+            kwargs['example_property'] = []
+
 List Command Options
 ====================