Deprecate parameter related methods in gitlab.Gitlab

These methods change the auth information and URL, and might have some
unwanted side effects.

Users should create a new Gitlab instance to change the URL and
authentication information.

3 files changed, 52 insertions, 33 deletions

diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst
index 79957ed..ed6617a 100644
--- a/RELEASE_NOTES.rst
+++ b/RELEASE_NOTES.rst
@@ -4,6 +4,20 @@ Release notes
 
 This page describes important changes between python-gitlab releases.
 
+Changes from 0.20 to 0.21
+=========================
+
+* Several methods have been deprecated in the ``gitlab.Gitlab`` class:
+
+  + ``credentials_auth()`` is deprecated and will be removed. Call ``auth()``.
+  + ``token_auth()`` is deprecated and will be removed. Call ``auth()``.
+  + ``set_url()`` is deprecated, create a new ``Gitlab`` instance if you need
+    an updated URL.
+  + ``set_token()`` is deprecated, use the ``private_token`` argument of the
+    ``Gitlab`` constructor.
+  + ``set_credentials()`` is deprecated, use the ``email`` and ``password``
+    arguments of the ``Gitlab`` constructor.
+
 Changes from 0.19 to 0.20
 =========================
 
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
index 1db03b0..7ea0a6a 100644
--- a/gitlab/__init__.py
+++ b/gitlab/__init__.py
@@ -76,7 +76,7 @@ class Gitlab(object):
         self.timeout = timeout
         #: Headers that will be used in request to GitLab
         self.headers = {}
-        self.set_token(private_token)
+        self._set_token(private_token)
         #: The user email
         self.email = email
         #: The user password (associated with email)
@@ -163,12 +163,17 @@ class Gitlab(object):
         success.
         """
         if self.private_token:
-            self.token_auth()
+            self._token_auth()
         else:
-            self.credentials_auth()
+            self._credentials_auth()
 
     def credentials_auth(self):
         """Performs an authentication using email/password."""
+        warnings.warn('credentials_auth() is deprecated and will be removed.',
+                      DeprecationWarning)
+        self._credentials_auth()
+
+    def _credentials_auth(self):
         if not self.email or not self.password:
             raise GitlabAuthenticationError("Missing email/password")
 
@@ -179,7 +184,16 @@ class Gitlab(object):
         """(gitlab.objects.CurrentUser): Object representing the user currently
             logged.
         """
-        self.set_token(self.user.private_token)
+        self._set_token(self.user.private_token)
+
+    def token_auth(self):
+        """Performs an authentication using the private token."""
+        warnings.warn('token_auth() is deprecated and will be removed.',
+                      DeprecationWarning)
+        self._token_auth()
+
+    def _token_auth(self):
+        self.user = CurrentUser(self)
 
     def version(self):
         """Returns the version and revision of the gitlab server.
@@ -202,16 +216,15 @@ class Gitlab(object):
 
         return self.version, self.revision
 
-    def token_auth(self):
-        """Performs an authentication using the private token."""
-        self.user = CurrentUser(self)
-
     def set_url(self, url):
         """Updates the GitLab URL.
 
         Args:
             url (str): Base URL of the GitLab server.
         """
+        warnings.warn('set_url() is deprecated, create a new Gitlab instance '
+                      'if you need an updated URL.',
+                      DeprecationWarning)
         self._url = '%s/api/v3' % url
 
     def _construct_url(self, id_, obj, parameters, action=None):
@@ -244,6 +257,12 @@ class Gitlab(object):
         Args:
             token (str): The private token.
         """
+        warnings.warn('set_token() is deprecated, use the private_token '
+                      'argument of the Gitlab constructor.',
+                      DeprecationWarning)
+        self._set_token(token)
+
+    def _set_token(self, token):
         self.private_token = token if token else None
         if token:
             self.headers["PRIVATE-TOKEN"] = token
@@ -257,6 +276,9 @@ class Gitlab(object):
             email (str): The user email or login.
             password (str): The user password.
         """
+        warnings.warn('set_credentials() is deprecated, use the email and '
+                      'password arguments of the Gitlab constructor.',
+                      DeprecationWarning)
         self.email = email
         self.password = password
 
diff --git a/gitlab/tests/test_gitlab.py b/gitlab/tests/test_gitlab.py
index 4670def..c2cd19b 100644
--- a/gitlab/tests/test_gitlab.py
+++ b/gitlab/tests/test_gitlab.py
@@ -341,7 +341,7 @@ class TestGitlabMethods(unittest.TestCase):
         self.assertRaises(GitlabListError, self.gl.list, ProjectBranch)
 
     def test_list_no_connection(self):
-        self.gl.set_url('http://localhost:66000')
+        self.gl._url = 'http://localhost:66000/api/v3'
         self.assertRaises(GitlabConnectionError, self.gl.list, ProjectBranch,
                           project_id=1)
 
@@ -613,27 +613,10 @@ class TestGitlab(unittest.TestCase):
                          email="testuser@test.com", password="testpassword",
                          ssl_verify=True)
 
-    def test_set_url(self):
-        self.gl.set_url("http://new_url")
-        self.assertEqual(self.gl._url, "http://new_url/api/v3")
-
-    def test_set_token(self):
-        token = "newtoken"
-        expected = {"PRIVATE-TOKEN": token}
-        self.gl.set_token(token)
-        self.assertEqual(self.gl.private_token, token)
-        self.assertDictContainsSubset(expected, self.gl.headers)
-
-    def test_set_credentials(self):
-        email = "credentialuser@test.com"
-        password = "credentialpassword"
-        self.gl.set_credentials(email=email, password=password)
-        self.assertEqual(self.gl.email, email)
-        self.assertEqual(self.gl.password, password)
-
     def test_credentials_auth_nopassword(self):
-        self.gl.set_credentials(email=None, password=None)
-        self.assertRaises(GitlabAuthenticationError, self.gl.credentials_auth)
+        self.gl.email = None
+        self.gl.password = None
+        self.assertRaises(GitlabAuthenticationError, self.gl._credentials_auth)
 
     def test_credentials_auth_notok(self):
         @urlmatch(scheme="http", netloc="localhost", path="/api/v3/session",
@@ -645,10 +628,10 @@ class TestGitlab(unittest.TestCase):
 
         with HTTMock(resp_cont):
             self.assertRaises(GitlabAuthenticationError,
-                              self.gl.credentials_auth)
+                              self.gl._credentials_auth)
 
     def test_auth_with_credentials(self):
-        self.gl.set_token(None)
+        self.gl.private_token = None
         self.test_credentials_auth(callback=self.gl.auth)
 
     def test_auth_with_token(self):
@@ -656,7 +639,7 @@ class TestGitlab(unittest.TestCase):
 
     def test_credentials_auth(self, callback=None):
         if callback is None:
-            callback = self.gl.credentials_auth
+            callback = self.gl._credentials_auth
         token = "credauthtoken"
         id_ = 1
         expected = {"PRIVATE-TOKEN": token}
@@ -677,7 +660,7 @@ class TestGitlab(unittest.TestCase):
 
     def test_token_auth(self, callback=None):
         if callback is None:
-            callback = self.gl.token_auth
+            callback = self.gl._token_auth
         name = "username"
         id_ = 1