Merge "Restrict direct usage of novaclient.v2.client"

2 files changed, 36 insertions, 41 deletions

diff --git a/novaclient/client.py b/novaclient/client.py
index 15925554..f7ac8702 100644
--- a/novaclient/client.py
+++ b/novaclient/client.py
@@ -785,6 +785,27 @@ def get_client_class(version):
 
 
 def Client(version, *args, **kwargs):
-    """Initialize client object based on given version."""
+    """Initialize client object based on given version.
+
+    HOW-TO:
+    The simplest way to create a client instance is initialization with your
+    credentials::
+
+        >>> from novaclient import client
+        >>> nova = client.Client(VERSION, USERNAME, PASSWORD,
+        ...                      PROJECT_ID, AUTH_URL)
+
+    Here ``VERSION`` can be a string or
+    ``novaclient.api_versions.APIVersion`` obj. If you prefer string value,
+    you can use ``1.1`` (deprecated now), ``2`` or ``2.X``
+    (where X is a microversion).
+
+
+    Alternatively, you can create a client instance using the keystoneclient
+    session API. See "The novaclient Python API" page at
+    python-novaclient's doc.
+    """
     api_version, client_class = _get_client_class_and_version(version)
-    return client_class(api_version=api_version, *args, **kwargs)
+    kwargs.pop("direct_use", None)
+    return client_class(api_version=api_version, direct_use=False,
+                        *args, **kwargs)
diff --git a/novaclient/v2/client.py b/novaclient/v2/client.py
index 1c195d5a..d48c062f 100644
--- a/novaclient/v2/client.py
+++ b/novaclient/v2/client.py
@@ -14,6 +14,7 @@
 #    under the License.
 
 from novaclient import client
+from novaclient.i18n import _LW
 from novaclient.v2 import agents
 from novaclient.v2 import aggregates
 from novaclient.v2 import availability_zones
@@ -53,44 +54,8 @@ class Client(object):
     """
     Top-level object to access the OpenStack Compute API.
 
-    Create an instance with your creds::
-
-        >>> client = Client(USERNAME, PASSWORD, PROJECT_ID, AUTH_URL)
-
-    Or, alternatively, you can create a client instance using the
-    keystoneclient.session API::
-
-        >>> from keystoneclient.auth.identity import v2
-        >>> from keystoneclient import session
-        >>> from novaclient import client
-        >>> auth = v2.Password(auth_url=AUTH_URL,
-                               username=USERNAME,
-                               password=PASSWORD,
-                               tenant_name=PROJECT_ID)
-        >>> sess = session.Session(auth=auth)
-        >>> nova = client.Client(VERSION, session=sess)
-
-    Then call methods on its managers::
-
-        >>> nova.servers.list()
-        ...
-        >>> nova.flavors.list()
-        ...
-
-    It is also possible to use an instance as a context manager in which
-    case there will be a session kept alive for the duration of the with
-    statement::
-
-        >>> with Client(USERNAME, PASSWORD, PROJECT_ID, AUTH_URL) as client:
-        ...     client.servers.list()
-        ...     client.flavors.list()
-        ...
-
-    It is also possible to have a permanent (process-long) connection pool,
-    by passing a connection_pool=True::
-
-        >>> client = Client(USERNAME, PASSWORD, PROJECT_ID,
-        ...     AUTH_URL, connection_pool=True)
+    .. warning:: All scripts and projects should not initialize this class
+      directly. It should be done via `novaclient.client.Client` interface.
     """
 
     def __init__(self, username=None, api_key=None, project_id=None,
@@ -103,7 +68,7 @@ class Client(object):
                  auth_system='keystone', auth_plugin=None, auth_token=None,
                  cacert=None, tenant_id=None, user_id=None,
                  connection_pool=False, session=None, auth=None,
-                 api_version=None, **kwargs):
+                 api_version=None, direct_use=True, **kwargs):
         """
         :param str username: Username
         :param str api_key: API Key
@@ -136,6 +101,15 @@ class Client(object):
         :param api_version: Compute API version
         :type api_version: novaclient.api_versions.APIVersion
         """
+        if direct_use:
+            import warnings
+
+            warnings.warn(
+                _LW("'novaclient.v2.client.Client' is not designed to be "
+                    "initialized directly. It is inner class of novaclient. "
+                    "Please, use 'novaclient.client.Client' instead. "
+                    "Related lp bug-report: 1493576"))
+
         # FIXME(comstud): Rename the api_key argument above when we
         # know it's not being used as keyword argument