From 403e6cad5e110362cf529cb8b27e6cbb6f5e4d00 Mon Sep 17 00:00:00 2001
From: Rui Chen <chenrui.momo@gmail.com>
Date: Thu, 28 Apr 2016 11:55:32 +0800
Subject: [PATCH] Add describe of overwrite options behavior into devref
Update the devref to add the describe and code example about
overwrite options behavior.
Change-Id: I65e9a3a30acf8d427906096bde24fa8b4c3ac3f7
Implements: blueprint allow-overwrite-set-options
---
doc/source/command-options.rst | 33 ++++++++++++++++++++++++++-------
1 file changed, 26 insertions(+), 7 deletions(-)
diff --git a/doc/source/command-options.rst b/doc/source/command-options.rst
index d47a56dc23..5cb84684c9 100644
--- a/doc/source/command-options.rst
+++ b/doc/source/command-options.rst
@@ -112,8 +112,26 @@ 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.
+``--no`` option on the ``set`` and ``unset`` actions. 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
+``--no`` 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:
+
+.. code-block:: bash
+
+ object set --example-property xxx
+
+Overwrite:
+
+.. code-block:: bash
+
+ 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
@@ -129,8 +147,7 @@ An example parser declaration for `set` action:
.. code-block:: python
- example_property_group = parser.add_mutually_exclusive_group()
- example_property_group.add_argument(
+ parser.add_argument(
'--example-property',
metavar='<example-property>',
dest='example_property',
@@ -138,7 +155,7 @@ An example parser declaration for `set` action:
help=_('Example property for this <resource> '
'(repeat option to set multiple properties)'),
)
- example_property_group.add_argument(
+ parser.add_argument(
'--no-example-property',
dest='no_example_property',
action='store_true',
@@ -149,10 +166,12 @@ An example handler in `take_action()` for `set` action:
.. code-block:: python
- if parsed_args.example_property:
+ if parsed_args.example_property and parsed_args.no_example_property:
+ kwargs['example_property'] = parsed_args.example_property
+ elif parsed_args.example_property:
kwargs['example_property'] = \
resource_example_property + parsed_args.example_property
- if parsed_args.no_example_property:
+ elif parsed_args.no_example_property:
kwargs['example_property'] = []
An example parser declaration for `unset` action: