feat: allow cfg timeout to be overrided via kwargs

On startup, the `timeout` parameter is loaded from config and stored on
the base gitlab object instance. This instance parameter is used as the
timeout for all API requests (it's passed into the `session` object when
making HTTP calls).

This change allows any API method to specify a `timeout` argument to
`**kwargs` that will override the global timeout value. This was
somewhat needed / helpful for the `import_github` method.

I have also updated the docs accordingly.

3 files changed, 32 insertions, 13 deletions

diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index fc2314e..d211e25 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -366,3 +366,20 @@ default an exception is raised for these errors.
 
    gl = gitlab.gitlab(url, token, api_version=4)
    gl.projects.list(all=True, retry_transient_errors=True)
+
+Timeout
+-------
+
+python-gitlab will by default use the ``timeout`` option from it's configuration
+for all requests. This is passed downwards to the ``requests`` module at the
+time of making the HTTP request. However if you would like to override the
+global timeout parameter for a particular call, you can provide the ``timeout``
+parameter to that API invocation:
+
+.. code-block:: python
+
+   import gitlab
+
+   gl = gitlab.gitlab(url, token, api_version=4)
+   gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)
+
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
index 03e5556..c4460a4 100644
--- a/gitlab/__init__.py
+++ b/gitlab/__init__.py
@@ -491,6 +491,8 @@ class Gitlab(object):
 
         verify = opts.pop("verify")
         timeout = opts.pop("timeout")
+        # If timeout was passed into kwargs, allow it to override the default
+        timeout = kwargs.get("timeout", timeout)
 
         # We need to deal with json vs. data when uploading files
         if files:
diff --git a/gitlab/v4/objects.py b/gitlab/v4/objects.py
index 7a1e7b8..65be16d 100644
--- a/gitlab/v4/objects.py
+++ b/gitlab/v4/objects.py
@@ -4745,13 +4745,7 @@ class ProjectManager(CRUDMixin, RESTManager):
         )
 
     def import_github(
-        self,
-        personal_access_token,
-        repo_id,
-        target_namespace,
-        new_name=None,
-        timeout_override=60.0,
-        **kwargs
+        self, personal_access_token, repo_id, target_namespace, new_name=None, **kwargs
     ):
         """Import a project from Github to Gitlab (schedule the import)
 
@@ -4761,15 +4755,14 @@ class ProjectManager(CRUDMixin, RESTManager):
         operation has completed.
 
         NOTE: this request may take longer than most other API requests.
-        So this method will override the session timeout with <timeout_override>,
-        which defaults to 60 seconds.
+        So this method will specify a 60 second default timeout if none is specified.
+        A timeout can be specified via kwargs to override this functionality.
 
         Args:
             personal_access_token (str): GitHub personal access token
             repo_id (int): Github repository ID
             target_namespace (str): Namespace to import repo into
             new_name (str): New repo name (Optional)
-            timeout_override (int or float): Timeout to use for this request
             **kwargs: Extra options to send to the server (e.g. sudo)
 
         Raises:
@@ -4801,10 +4794,17 @@ class ProjectManager(CRUDMixin, RESTManager):
         }
         if new_name:
             data["new_name"] = new_name
-        prev_timeout = self.gitlab.timeout
-        self.gitlab.timeout = timeout_override
+        if (
+            "timeout" not in kwargs
+            or self.gitlab.timeout is None
+            or self.gitlab.timeout < 60.0
+        ):
+            # Ensure that this HTTP request has a longer-than-usual default timeout
+            # The base gitlab object tends to have a default that is <10 seconds,
+            # and this is too short for this API command, typically.
+            # On the order of 24 seconds has been measured on a typical gitlab instance.
+            kwargs["timeout"] = 60.0
         result = self.gitlab.http_post("/import/github", post_data=data, **kwargs)
-        self.gitlab.timeout = prev_timeout
         return result