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

3 files changed, 49 insertions, 0 deletions

diff --git a/README.rst b/README.rst
index 99ed287..3d97476 100644
--- a/README.rst
+++ b/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
 -----------------------------
 
diff --git a/os_client_config/__init__.py b/os_client_config/__init__.py
index 6142853..09d7442 100644
--- a/os_client_config/__init__.py
+++ b/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)
diff --git a/releasenotes/notes/shade-helper-568f8cb372eef6d9.yaml b/releasenotes/notes/shade-helper-568f8cb372eef6d9.yaml
new file mode 100644
index 0000000..70aab0a
--- /dev/null
+++ b/releasenotes/notes/shade-helper-568f8cb372eef6d9.yaml
@@ -0,0 +1,4 @@
+---
+features:
+  - Added helper method for constructing shade
+    OpenStackCloud objects.