Clarify argparse connections

The user guide shows that options passed to connection.from_config do
not have to be an argparse Namespace, contrary to the comments in
connection.from_config. This change corrects those comments and adds
a user guide example showing how argparse may be used.

Change-Id: I2a9e92cbf0aab16476001be772034e9698a24c9f
Closes-Bug: #1629331

doc/source/users/guides/connect_from_config.rst

@@ -32,12 +32,13 @@ locations:
 * /etc/openstack
 
 call :py:func:`~openstack.connection.from_config`. The ``from_config``
-function takes three optional arguments, such as **cloud_name**,
-which allows you to specify one set of cloud credentials in your
-``clouds.yaml`` file. Additionally, **cloud_config** and **options**
-allow you to pass in configiration data you may have already received
-from ``os-client-config``, as well as additional options that the
-``os-client-config`` library may need.
+function takes three optional arguments:
+
+* **cloud_name** allows you to specify a cloud from your ``clouds.yaml`` file.
+* **cloud_config** allows you to pass in an existing
+``os_client_config.config.OpenStackConfig``` object.
+* **options** allows you to specify a namespace object with options to be
+added to the cloud config.
 
 .. literalinclude:: ../examples/connect.py
    :pyobject: Opts
@@ -45,7 +46,10 @@ from ``os-client-config``, as well as additional options that the
 .. literalinclude:: ../examples/connect.py
    :pyobject: create_connection_from_config
 
-.. note:: To enable logging, set ``debug=True`` in the ``Opts`` object.
+.. literalinclude:: ../examples/connect.py
+   :pyobject: create_connection_from_args
+
+.. note:: To enable logging, set ``debug=True`` in the ``options`` object.
 
 User Defined Location
 *********************

examples/connect.py

@@ -16,6 +16,7 @@ Connect to an OpenStack cloud.
 For a full guide see TODO(etoews):link to docs on developer.openstack.org
 """
 
+import argparse
 import os
 
 import os_client_config
@@ -48,9 +49,8 @@ def _get_resource_value(resource_key, default):
     except KeyError:
         return default
 
-opts = Opts(cloud_name=TEST_CLOUD)
 occ = os_client_config.OpenStackConfig()
-cloud = occ.get_one_cloud(opts.cloud, argparse=opts)
+cloud = occ.get_one_cloud(TEST_CLOUD)
 
 SERVER_NAME = 'openstacksdk-example'
 IMAGE_NAME = _get_resource_value('image_name', 'cirros-0.3.4-x86_64-uec')
@@ -67,9 +67,20 @@ EXAMPLE_IMAGE_NAME = 'openstacksdk-example-public-image'
 
 
 def create_connection_from_config():
+    opts = Opts(cloud_name=TEST_CLOUD)
+    occ = os_client_config.OpenStackConfig()
+    cloud = occ.get_one_cloud(opts.cloud)
     return connection.from_config(cloud_config=cloud, options=opts)
 
 
+def create_connection_from_args():
+    parser = argparse.ArgumentParser()
+    config = os_client_config.OpenStackConfig()
+    config.register_argparse_arguments(parser, sys.argv[1:])
+    args = parser.parse_args()
+    return connection.from_config(options=args)
+
+
 def create_connection(auth_url, region, project_name, username, password):
     prof = profile.Profile()
     prof.set_region(profile.Profile.ALL, region)

openstack/connection.py

@@ -86,10 +86,11 @@ def from_config(cloud_name=None, cloud_config=None, options=None):
                          determining which cloud's configuration details
                          will be used in creation of the
                          `Connection` instance.
-    :param options: An argparse Namespace object; allows direct passing
-                    in of argparse options to be added to the cloud config.
-                    This value is passed to the `argparse` argument of
-                    `os_client_config.config.OpenStackConfig.get_one_cloud`.
+    :param options: A namespace object; allows direct passing in of options to
+                    be added to the cloud config. This does not have to be an
+                    instance of argparse.Namespace, despite the naming of the
+                    the `os_client_config.config.OpenStackConfig.get_one_cloud`
+                    argument to which it is passed.
 
     :rtype: :class:`~openstack.connection.Connection`
     """