diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/commands.rst | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/doc/source/commands.rst b/doc/source/commands.rst new file mode 100644 index 00000000..40a24258 --- /dev/null +++ b/doc/source/commands.rst @@ -0,0 +1,60 @@ +======== +Commands +======== + +Command Structure +================= + +OpenStack Client uses a command form ``verb object``. + +Note that 'object' here refers to the target of a command's action. In coding +discussions 'object' has its usual Python meaning. Go figure. + +Commands take the form:: + + openstack [<global-options>] <verb> <object> [<command-local-arguments>] + +Command Arguments +----------------- + + * All long option names use two dashes ('--') as the prefix and a single dash + ('-') as the interpolation character. Some common options also have the + traditional single letter name prefixed by a single dash ('-'). + * Global options generally have a corresponding environment variable that + may also be used to set the value. If both are present, the command-line + option takes priority. The environment variable names can be derived from + the option name by dropping the leading '--', converting all embedded dashes + ('-') to underscores ('_'), and converting the name to upper case. + * Positional arguments trail command options. In commands that require two or + more objects be acted upon, such as 'attach A to B', both objects appear + as positional arguments. If they also appear in the command object they are + in the same order. + + +Implementation +============== + +The command structure is designed to support seamless addition of extension +command modules via entry points. The extensions are assumed to be subclasses +of Cliff's command.Command object. + +Command Entry Points +-------------------- + +Commands are added to the client using distribute's entry points in ``setup.py``. +There is a single common group ``openstack.cli`` for commands that are not versioned, +and a group for each combination of OpenStack API and version that is +supported. For example, to support Identity API v3 there is a group called +``openstack.identity.v3`` that contains the individual commands. The command +entry points have the form:: + + "verb_object=fully.qualified.module.vXX.object:VerbObject" + +For example, the 'list user' command fir the Identity API is identified in +``setup.py`` with:: + + 'openstack.identity.v3': [ + # ... + 'list_user=openstackclient.identity.v3.user:ListUser', + # ... + ], |