Merge "Update docs and release notes for 0.4.1 release"0.4.1

1 files changed, 54 insertions, 1 deletions

diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
index 690c1269..3b35ec08 100644
--- a/doc/source/plugins.rst
+++ b/doc/source/plugins.rst
@@ -20,7 +20,7 @@ client module.
     openstack.cli.extension =
         oscplugin = oscplugin.client
 
-The client module must implement the following interface functions:
+The client module must define the following top-level variables:
 
 * ``API_NAME`` - A string containing the plugin API name; this is
   the name of the entry point declaring the plugin client module
@@ -30,6 +30,9 @@ The client module must implement the following interface functions:
   version attribute; this must be a valid Python identifier and
   match the destination set in ``build_option_parser()``.
 * ``API_VERSIONS`` - A dict mapping a version string to the client class
+
+The client module must implement the following interface functions:
+
 * ``build_option_parser(parser)`` - Hook to add global options to the parser
 * ``make_client(instance)`` - Hook to create the client object
 
@@ -44,3 +47,53 @@ defined for the API version:
 
 Note that OSC defines the group name as :py:mod:`openstack.<api-name>.v<version>`
 so the version should not contain the leading 'v' character.
+
+::
+
+    DEFAULT_OSCPLUGIN_API_VERSION = '1'
+
+    # Required by the OSC plugin interface
+    API_NAME = 'oscplugin'
+    API_VERSION_OPTION = 'os_oscplugin_api_version'
+    API_VERSIONS = {
+        '1': 'oscplugin.v1.client.Client',
+    }
+
+    # Required by the OSC plugin interface
+    def make_client(instance):
+        """Returns a client to the ClientManager
+
+        Called to instantiate the requested client version.  instance has
+        any available auth info that may be required to prepare the client.
+
+        :param ClientManager instance: The ClientManager that owns the new client
+        """
+        plugin_client = utils.get_client_class(
+            API_NAME,
+            instance._api_version[API_NAME],
+            API_VERSIONS)
+
+        client = plugin_client()
+        return client
+
+    # Required by the OSC plugin interface
+    def build_option_parser(parser):
+        """Hook to add global options
+
+        Called from openstackclient.shell.OpenStackShell.__init__()
+        after the builtin parser has been initialized.  This is
+        where a plugin can add global options such as an API version setting.
+
+        :param argparse.ArgumentParser parser: The parser object that has been
+            initialized by OpenStackShell.
+        """
+        parser.add_argument(
+            '--os-oscplugin-api-version',
+            metavar='<oscplugin-api-version>',
+            default=utils.env(
+                'OS_OSCPLUGIN_API_VERSION',
+                default=DEFAULT_OSCPLUGIN_API_VERSION),
+            help='OSC Plugin API version, default=' +
+                 DEFAULT_OSCPLUGIN_API_VERSION +
+                 ' (Env: OS_OSCPLUGIN_API_VERSION)')
+        return parser