chore: make `Gitlab.http_request()` a private methodjlvillal/http_request

Convert `Gitlab.http_request()` to `Gitlab._http_request()` to signify
it is a private/protected method so that users of the library know
they should not use the method and we make no API stability promises
for using it.

Add a `Gitlab.http_request()` method which will issue a Deprecation
warning when called. It will pass the call onto
`Gitlab._http_request()`

Also, in the interest of improving code read-ability, require keyword
arg usage when calling `Gitlab._http_request()`

2 files changed, 84 insertions, 21 deletions

diff --git a/gitlab/client.py b/gitlab/client.py
index b791c8f..72e9816 100644
--- a/gitlab/client.py
+++ b/gitlab/client.py
@@ -18,6 +18,7 @@
 
 import os
 import time
+import warnings
 from typing import Any, cast, Dict, List, Optional, Tuple, TYPE_CHECKING, Union
 
 import requests
@@ -549,7 +550,7 @@ class Gitlab(object):
 
     def _check_redirects(self, result: requests.Response) -> None:
         # Check the requests history to detect 301/302 redirections.
-        # If the initial verb is POST or PUT, the redirected request will use a
+        # If the initial method is POST or PUT, the redirected request will use a
         # GET request, leading to unwanted behaviour.
         # If we detect a redirection with a POST or a PUT request, we
         # raise an exception with a useful error message.
@@ -618,10 +619,44 @@ class Gitlab(object):
         max_retries: int = 10,
         **kwargs: Any,
     ) -> requests.Response:
+        warnings.warn(
+            "The Gitlab.http_request() method is deprecated and will be removed in a "
+            "future version. This is a private method and should not be used.",
+            DeprecationWarning,
+        )
+        return self._http_request(
+            method=verb,
+            path=path,
+            query_data=query_data,
+            post_data=post_data,
+            raw=raw,
+            streamed=streamed,
+            files=files,
+            timeout=timeout,
+            obey_rate_limit=obey_rate_limit,
+            max_retries=max_retries,
+            **kwargs,
+        )
+
+    def _http_request(
+        self,
+        *,
+        method: str,
+        path: str,
+        query_data: Optional[Dict[str, Any]] = None,
+        post_data: Optional[Union[Dict[str, Any], bytes]] = None,
+        raw: bool = False,
+        streamed: bool = False,
+        files: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        obey_rate_limit: bool = True,
+        max_retries: int = 10,
+        **kwargs: Any,
+    ) -> requests.Response:
         """Make an HTTP request to the Gitlab server.
 
         Args:
-            verb: The HTTP method to call ('get', 'post', 'put', 'delete')
+            method: The HTTP method to call ('get', 'post', 'put', 'delete')
             path: Path or full URL to query ('/projects' or
                         'http://whatever/v4/api/projecs')
             query_data: Data to send as query parameters
@@ -678,7 +713,7 @@ class Gitlab(object):
         cur_retries = 0
         while True:
             result = self.session.request(
-                method=verb,
+                method=method,
                 url=url,
                 json=json,
                 data=data,
@@ -758,8 +793,8 @@ class Gitlab(object):
             GitlabParsingError: If the json data could not be parsed
         """
         query_data = query_data or {}
-        result = self.http_request(
-            "get", path, query_data=query_data, streamed=streamed, **kwargs
+        result = self._http_request(
+            method="get", path=path, query_data=query_data, streamed=streamed, **kwargs
         )
 
         if (
@@ -855,9 +890,9 @@ class Gitlab(object):
         query_data = query_data or {}
         post_data = post_data or {}
 
-        result = self.http_request(
-            "post",
-            path,
+        result = self._http_request(
+            method="post",
+            path=path,
             query_data=query_data,
             post_data=post_data,
             files=files,
@@ -903,9 +938,9 @@ class Gitlab(object):
         query_data = query_data or {}
         post_data = post_data or {}
 
-        result = self.http_request(
-            "put",
-            path,
+        result = self._http_request(
+            method="put",
+            path=path,
             query_data=query_data,
             post_data=post_data,
             files=files,
@@ -933,7 +968,7 @@ class Gitlab(object):
         Raises:
             GitlabHttpError: When the return code is not 2xx
         """
-        return self.http_request("delete", path, **kwargs)
+        return self._http_request(method="delete", path=path, **kwargs)
 
     @gitlab.exceptions.on_http_error(gitlab.exceptions.GitlabSearchError)
     def search(
@@ -987,7 +1022,9 @@ class GitlabList(object):
         self, url: str, query_data: Optional[Dict[str, Any]] = None, **kwargs: Any
     ) -> None:
         query_data = query_data or {}
-        result = self._gl.http_request("get", url, query_data=query_data, **kwargs)
+        result = self._gl._http_request(
+            method="get", path=url, query_data=query_data, **kwargs
+        )
         try:
             links = result.links
             if links:
diff --git a/tests/unit/test_gitlab_http_methods.py b/tests/unit/test_gitlab_http_methods.py
index ba57c31..af78cad 100644
--- a/tests/unit/test_gitlab_http_methods.py
+++ b/tests/unit/test_gitlab_http_methods.py
@@ -1,3 +1,5 @@
+import warnings
+
 import pytest
 import requests
 from httmock import HTTMock, response, urlmatch
@@ -22,11 +24,31 @@ def test_http_request(gl):
         return response(200, content, headers, None, 5, request)
 
     with HTTMock(resp_cont):
-        http_r = gl.http_request("get", "/projects")
+        http_r = gl._http_request(method="get", path="/projects")
         http_r.json()
         assert http_r.status_code == 200
 
 
+def test_http_request_deprecated(gl):
+    @urlmatch(scheme="http", netloc="localhost", path="/api/v4/projects", method="get")
+    def resp_cont(url, request):
+        headers = {"content-type": "application/json"}
+        content = '[{"name": "project1"}]'
+        return response(200, content, headers, None, 5, request)
+
+    with warnings.catch_warnings(record=True) as caught_warnings:
+        with HTTMock(resp_cont):
+            http_r = gl.http_request(verb="get", path="/projects")
+            http_r.json()
+            assert http_r.status_code == 200
+    assert len(caught_warnings) == 1
+    warning = caught_warnings[0]
+    assert isinstance(warning.message, DeprecationWarning)
+    message = str(caught_warnings[0].message)
+    assert "deprecated" in message
+    assert "Gitlab.http_request()" in message
+
+
 def test_http_request_404(gl):
     @urlmatch(scheme="http", netloc="localhost", path="/api/v4/not_there", method="get")
     def resp_cont(url, request):
@@ -35,7 +57,7 @@ def test_http_request_404(gl):
 
     with HTTMock(resp_cont):
         with pytest.raises(GitlabHttpError):
-            gl.http_request("get", "/not_there")
+            gl._http_request(method="get", path="/not_there")
 
 
 @pytest.mark.parametrize("status_code", [500, 502, 503, 504])
@@ -50,7 +72,7 @@ def test_http_request_with_only_failures(gl, status_code):
 
     with HTTMock(resp_cont):
         with pytest.raises(GitlabHttpError):
-            gl.http_request("get", "/projects")
+            gl._http_request(method="get", path="/projects")
 
     assert call_count == 1
 
@@ -74,7 +96,9 @@ def test_http_request_with_retry_on_method_for_transient_failures(gl):
         )
 
     with HTTMock(resp_cont):
-        http_r = gl.http_request("get", "/projects", retry_transient_errors=True)
+        http_r = gl._http_request(
+            method="get", path="/projects", retry_transient_errors=True
+        )
 
         assert http_r.status_code == 200
         assert call_count == calls_before_success
@@ -99,7 +123,7 @@ def test_http_request_with_retry_on_class_for_transient_failures(gl_retry):
         )
 
     with HTTMock(resp_cont):
-        http_r = gl_retry.http_request("get", "/projects")
+        http_r = gl_retry._http_request(method="get", path="/projects")
 
         assert http_r.status_code == 200
         assert call_count == calls_before_success
@@ -118,7 +142,9 @@ def test_http_request_with_retry_on_class_and_method_for_transient_failures(gl_r
 
     with HTTMock(resp_cont):
         with pytest.raises(GitlabHttpError):
-            gl_retry.http_request("get", "/projects", retry_transient_errors=False)
+            gl_retry._http_request(
+                method="get", path="/projects", retry_transient_errors=False
+            )
 
         assert call_count == 1
 
@@ -181,7 +207,7 @@ def test_http_request_302_get_does_not_raise(gl):
         return resp_obj
 
     with HTTMock(resp_cont):
-        gl.http_request(verb=method, path=api_path)
+        gl._http_request(method=method, path=api_path)
 
 
 def test_http_request_302_put_raises_redirect_error(gl):
@@ -203,7 +229,7 @@ def test_http_request_302_put_raises_redirect_error(gl):
 
     with HTTMock(resp_cont):
         with pytest.raises(RedirectError) as exc:
-            gl.http_request(verb=method, path=api_path)
+            gl._http_request(method=method, path=api_path)
         error_message = exc.value.error_message
         assert "Moved Temporarily" in error_message
         assert "http://localhost/api/v4/user/status" in error_message