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.

1 files changed, 17 insertions, 0 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)
+