136 lines
3.9 KiB
ReStructuredText
136 lines
3.9 KiB
ReStructuredText
===============
|
|
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 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 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 <resource> (default)
|
|
|
|
.. option:: --disable
|
|
|
|
Disable <resource>
|
|
|
|
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 <resource> (default)'),
|
|
)
|
|
enable_group.add_argument(
|
|
'--disable',
|
|
action='store_true',
|
|
help=_('Disable <resource>'),
|
|
)
|
|
|
|
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 <marker>
|
|
|
|
Anchor for paging
|
|
|
|
.. option:: --limit <limit>
|
|
|
|
Limit number of <resource> returned (*integer*)
|
|
|
|
Implementation
|
|
~~~~~~~~~~~~~~
|
|
|
|
The parser declaration should look like this::
|
|
|
|
.. code-block: python
|
|
|
|
parser.add_argument(
|
|
"--marker",
|
|
metavar="<marker>",
|
|
help="Anchor for paging",
|
|
)
|
|
|
|
parser.add_argument(
|
|
"--limit",
|
|
metavar="<limit>",
|
|
type=int,
|
|
help="Limit the number of <resource> returned",
|
|
)
|