Properly deprecate v1.client and some other client related things

v1.client is already deprecated since 2015-09 [1] but we never said when the
code will be eventually removed. It's now explicitly mentioned that
v1.client will be removed with the 2.0.0 release of python-manilaclient.
Also explicitly mention that some kwargs (for v1.client.Client and
v2.client.Client) and the authenticate() method (also for v1 and v2) will
be removed with the 2.0.0 release.

[1] I3733fe85424e39566addc070d42609e508259f19

Change-Id: I3de36f69c43245a5d27279c5fb7226f0f1cee2e0

manilaclient/v1/client.py

@@ -10,7 +10,7 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-import warnings
+from debtcollector import removals
 
 from keystoneauth1 import session
 from keystoneclient import adapter
@@ -35,6 +35,8 @@ from manilaclient.v2 import share_types
 from manilaclient.v2 import shares
 
 
+@removals.removed_class("Client", message="Please use 'v2.Client' instead",
+                        removal_version='2.0.0')
 class Client(object):
     """Top-level object to access the OpenStack Manila API.
 
@@ -60,6 +62,21 @@ class Client(object):
         >>> client.shares.list()
         ...
     """
+    @removals.removed_kwarg(
+        'share_service_name', message="Please use 'service_name' instead",
+        removal_version='2.0.0')
+    @removals.removed_kwarg(
+        'proxy_tenant_id', message="This is not used anywhere",
+        removal_version='2.0.0')
+    @removals.removed_kwarg(
+        'proxy_token', message="This is not used anywhere",
+        removal_version='2.0.0')
+    @removals.removed_kwarg(
+        'os_cache', message="Please use 'use_keyring' instead",
+        removal_version='2.0.0')
+    @removals.removed_kwarg(
+        'api_key', message="Please use 'password' instead",
+        removal_version='2.0.0')
     def __init__(self, username=None, api_key=None,
                  project_id=None, auth_url=None, insecure=False, timeout=None,
                  tenant_id=None, project_name=None, region_name=None,
@@ -107,32 +124,6 @@ class Client(object):
 
         service_name = kwargs.get("share_service_name", service_name)
 
-        def check_deprecated_arguments():
-            deprecated = {
-                'share_service_name': 'service_name',
-                'proxy_tenant_id': None,
-                'proxy_token': None,
-                'os_cache': 'use_keyring',
-                'api_key': 'password',
-            }
-
-            for arg, replacement in deprecated.items():
-                if kwargs.get(arg, None) is None:
-                    continue
-
-                replacement_msg = ""
-
-                if replacement is not None:
-                    replacement_msg = " Use %s instead." % replacement
-
-                msg = "Argument %(arg)s is deprecated.%(repl)s" % {
-                    'arg': arg,
-                    'repl': replacement_msg
-                }
-                warnings.warn(msg)
-
-        check_deprecated_arguments()
-
         if input_auth_token and not service_catalog_url:
             msg = ("For token-based authentication you should "
                    "provide 'input_auth_token' and 'service_catalog_url'.")
@@ -223,6 +214,10 @@ class Client(object):
             if extension.manager_class:
                 setattr(self, extension.name, extension.manager_class(self))
 
+    @removals.remove(
+        message="authenticate() method is deprecated. Client automatically "
+        "makes authentication call in the constructor.",
+        removal_version='2.0.0')
     def authenticate(self):
         """Authenticate against the server.
 
@@ -232,9 +227,7 @@ class Client(object):
         Returns on success; raises :exc:`exceptions.Unauthorized` if the
         credentials are wrong.
         """
-        warnings.warn("authenticate() method is deprecated. "
+        pass
-                      "Client automatically makes authentication call "
-                      "in the constructor.")
 
     def _get_keystone_client(self):
         # First create a Keystone session

manilaclient/v2/client.py

@@ -10,7 +10,7 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-import warnings
+from debtcollector import removals
 
 from keystoneauth1 import session
 from keystoneclient import adapter
@@ -73,6 +73,21 @@ class Client(object):
         >>> client.shares.list()
         ...
     """
+    @removals.removed_kwarg(
+        'share_service_name', message="Please use 'service_name' instead",
+        removal_version='2.0.0')
+    @removals.removed_kwarg(
+        'proxy_tenant_id', message="This is not used anywhere",
+        removal_version='2.0.0')
+    @removals.removed_kwarg(
+        'proxy_token', message="This is not used anywhere",
+        removal_version='2.0.0')
+    @removals.removed_kwarg(
+        'os_cache', message="Please use 'use_keyring' instead",
+        removal_version='2.0.0')
+    @removals.removed_kwarg(
+        'api_key', message="Please use 'password' instead",
+        removal_version='2.0.0')
     def __init__(self, username=None, api_key=None,
                  project_id=None, auth_url=None, insecure=False, timeout=None,
                  tenant_id=None, project_name=None, region_name=None,
@@ -120,32 +135,6 @@ class Client(object):
 
         service_name = kwargs.get("share_service_name", service_name)
 
-        def check_deprecated_arguments():
-            deprecated = {
-                'share_service_name': 'service_name',
-                'proxy_tenant_id': None,
-                'proxy_token': None,
-                'os_cache': 'use_keyring',
-                'api_key': 'password',
-            }
-
-            for arg, replacement in deprecated.items():
-                if kwargs.get(arg, None) is None:
-                    continue
-
-                replacement_msg = ""
-
-                if replacement is not None:
-                    replacement_msg = " Use %s instead." % replacement
-
-                msg = "Argument %(arg)s is deprecated.%(repl)s" % {
-                    'arg': arg,
-                    'repl': replacement_msg
-                }
-                warnings.warn(msg)
-
-        check_deprecated_arguments()
-
         if input_auth_token and not service_catalog_url:
             msg = ("For token-based authentication you should "
                    "provide 'input_auth_token' and 'service_catalog_url'.")
@@ -260,6 +249,10 @@ class Client(object):
             if extension.manager_class:
                 setattr(self, extension.name, extension.manager_class(self))
 
+    @removals.remove(
+        message="authenticate() method is deprecated. Client automatically "
+        "makes authentication call in the constructor.",
+        removal_version='2.0.0')
     def authenticate(self):
         """Authenticate against the server.
 
@@ -269,9 +262,7 @@ class Client(object):
         Returns on success; raises :exc:`exceptions.Unauthorized` if the
         credentials are wrong.
         """
-        warnings.warn("authenticate() method is deprecated. "
+        pass
-                      "Client automatically makes authentication call "
-                      "in the constructor.")
 
     def _get_keystone_client(self):
         # First create a Keystone session

releasenotes/notes/deprecate-v1-a0cfa6fd723c2f46.yaml

@@ -0,0 +1,14 @@
+---
+deprecations:
+  - |
+    v1.Client is deprecated and will be removed with the 2.0.0 release of
+    python-manilaclient. Please use v2.Client.
+  - |
+    Some kwargs when creating a Client instance (for v1.Client and v2.Client)
+    are deprecated and will be removed with the 2.0.0 release of
+    python-manilaclient. The arguments are 'share_service_name',
+    'proxy_tenant_id', 'proxy_token', 'os_cache' and 'api_key'.
+  - |
+    The method 'authenticate()' for a v1.Client and v2.Client instance is
+    deprecated and will be removed with the 2.0.0 release of
+    python-manilaclient.

requirements.txt

@@ -16,3 +16,4 @@ simplejson>=3.5.1 # MIT
 Babel!=2.4.0,>=2.3.4 # BSD
 six>=1.9.0 # MIT
 python-keystoneclient>=3.8.0 # Apache-2.0
+debtcollector>=1.2.0  # Apache-2.0