From 7d63f12eddb250542587cab8e4a2ca9088ec0fbb Mon Sep 17 00:00:00 2001
From: Monty Taylor <mordred@inaugust.com>
Date: Wed, 1 Jun 2016 10:37:58 +0300
Subject: [PATCH] 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                                    | 33 +++++++++++++++++++
 os_client_config/__init__.py                  | 12 +++++++
 .../notes/shade-helper-568f8cb372eef6d9.yaml  |  4 +++
 3 files changed, 49 insertions(+)
 create mode 100644 releasenotes/notes/shade-helper-568f8cb372eef6d9.yaml

diff --git a/README.rst b/README.rst
index 99ed287b9..3d97476b1 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 6142853ef..09d74423b 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 000000000..70aab0a13
--- /dev/null
+++ b/releasenotes/notes/shade-helper-568f8cb372eef6d9.yaml
@@ -0,0 +1,4 @@
+---
+features:
+  - Added helper method for constructing shade
+    OpenStackCloud objects.