Advanced usage

Using a custom session

python-gitlab relies on ``requests.Session`` objects to perform all the

HTTP requests to the Gitlab servers.

You can provide your own ``Session`` object with custom configuration when

you create a ``Gitlab`` object.

Context manager

You can use ``Gitlab`` objects as context managers. This makes sure that the

``requests.Session`` object associated with a ``Gitlab`` instance is always

properly closed when you exit a ``with`` block:

.. code-block:: python

.. warning::

The context manager will also close the custom ``Session`` object you might

have used to build the ``Gitlab`` instance.

Proxy configuration

The following sample illustrates how to define a proxy configuration when using

python-gitlab:

.. code-block:: python

Reference:

https://requests.readthedocs.io/en/latest/user/advanced/#proxies

SSL certificate verification

python-gitlab relies on the CA certificate bundle in the `certifi` package

that comes with the requests library.

If you need python-gitlab to use your system CA store instead, you can provide

the path to the CA bundle in the `REQUESTS_CA_BUNDLE` environment variable.

Reference:

https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification

Client side certificate

The following sample illustrates how to use a client-side certificate:

.. code-block:: python

Reference:

https://requests.readthedocs.io/en/latest/user/advanced/#client-side-certificates

Rate limits

python-gitlab obeys the rate limit of the GitLab server by default. On

receiving a 429 response (Too Many Requests), python-gitlab sleeps for the

amount of time in the Retry-After header that GitLab sends back. If GitLab

does not return a response with the Retry-After header, python-gitlab will

perform an exponential backoff.

If you don't want to wait, you can disable the rate-limiting feature, by

supplying the ``obey_rate_limit`` argument.

.. code-block:: python

If you do not disable the rate-limiting feature, you can supply a custom value

for ``max_retries``; by default, this is set to 10. To retry without bound when

throttled, you can set this parameter to -1. This parameter is ignored if

``obey_rate_limit`` is set to ``False``.

.. code-block:: python

.. warning::

You will get an Exception, if you then go over the rate limit of your GitLab instance.

Transient errors

GitLab server can sometimes return a transient HTTP error.

python-gitlab can automatically retry in such case, when

``retry_transient_errors`` argument is set to ``True``. When enabled,

HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway),

503 (Service Unavailable), and 504 (Gateway Timeout) are retried. It will retry until reaching

the `max_retries` value. By default, `retry_transient_errors` is set to `False` and an exception

is raised for these errors.

.. code-block:: python

The default ``retry_transient_errors`` can also be set on the ``Gitlab`` object

and overridden by individual API calls.

.. code-block:: python

Timeout

python-gitlab will by default use the ``timeout`` option from its 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

api-usage-advanced