Add shade constructor helper method

We have helper factory methods for REST Client, legacy client and
OpenStack SDK all with the same interface ... we might as well have one
for shade too. It makes documenting and talking about the simple case of
all of them easy.

Change-Id: I046da85ae4a3e2a6333223921d5ae9ce3673121d

README.rst

@@ -392,6 +392,39 @@ for additional flexibility. If the helper function here does not meet your
 needs, you should see the `from_config` method of
 `openstack.connection.Connection <http://developer.openstack.org/sdks/python/openstacksdk/users/guides/connect_from_config.html>`_
 
+Constructing shade objects
+--------------------------
+
+If what you want to do is get a
+`shade <http://docs.openstack.org/infra/shade/>`_ OpenStackCloud object, a
+helper function that honors clouds.yaml and `OS_` environment variables is
+provided. The following will get you a fully configured `OpenStackCloud`
+instance.
+
+.. code-block:: python
+
+  import os_client_config
+
+  cloud = os_client_config.make_shade()
+
+If you want to do the same thing but on a named cloud.
+
+.. code-block:: python
+
+  import os_client_config
+
+  cloud = os_client_config.make_shade(cloud='mtvexx')
+
+If you want to do the same thing but also support command line parsing.
+
+.. code-block:: python
+
+  import argparse
+
+  import os_client_config
+
+  cloud = os_client_config.make_shade(options=argparse.ArgumentParser())
+
 Constructing REST API Clients
 -----------------------------
 

os_client_config/__init__.py

@@ -82,3 +82,15 @@ def make_sdk(options=None, **kwargs):
     from openstack import connection
     cloud = get_config(options=options, **kwargs)
     return connection.from_config(cloud_config=cloud, options=options)
+
+
+def make_shade(options=None, **kwargs):
+    """Simple wrapper for getting a Shade OpenStackCloud object
+
+    A mechanism that matches make_sdk, make_client and make_rest_client.
+
+    :rtype: :class:`~shade.OpenStackCloud`
+    """
+    import shade
+    cloud = get_config(options=options, **kwargs)
+    return shade.OpenStackCloud(cloud_config=cloud, **kwargs)

releasenotes/notes/shade-helper-568f8cb372eef6d9.yaml

@@ -0,0 +1,4 @@
+---
+features:
+  - Added helper method for constructing shade
+    OpenStackCloud objects.