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.

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:

with gitlab.Gitlab(host, token) as gl:
    gl.projects.list()

The following sample illustrates how to define a proxy configuration when using python-gitlab:

import os
import gitlab
import requests

session = requests.Session()
session.proxies = {
    'https': os.environ.get('https_proxy'),
    'http': os.environ.get('http_proxy'),
}
gl = gitlab.gitlab(url, token, api_version=4, session=session)

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

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

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

import gitlab
import requests

session = requests.Session()
session.cert = ('/path/to/client.cert', '/path/to/client.key')
gl = gitlab.gitlab(url, token, api_version=4, session=session)

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

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.

import gitlab
import requests

gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.list(get_all=True, obey_rate_limit=False)

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.

import gitlab
import requests

gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.list(get_all=True, max_retries=12)

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), 504 (Gateway Timeout), and Cloudflare errors (520-530) are retried.

Additionally, HTTP error code 409 (Conflict) is retried if the reason is a Resource lock.

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.

import gitlab
import requests

gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.list(get_all=True, retry_transient_errors=True)

The default retry_transient_errors can also be set on the Gitlab object and overridden by individual API calls.

import gitlab
import requests
gl = gitlab.gitlab(url, token, api_version=4, retry_transient_errors=True)
gl.projects.list(get_all=True)                               # retries due to default value
gl.projects.list(get_all=True, retry_transient_errors=False) # does not retry

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:

import gitlab

gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)

Generally, python-gitlab is a fully typed package. However, currently you may still need to do some type narrowing on your own, such as for nested API responses and Union return types. For example:

from typing import TYPE_CHECKING

import gitlab

gl = gitlab.gitlab(url, token, api_version=4)
license = gl.get_license()

if TYPE_CHECKING:
   assert isinstance(license["plan"], str)

You can use configuration files and a custom session to create gitlab.Gitlab objects:

gl = gitlab.Gitlab.from_config('somewhere', ['/tmp/gl.cfg'], session=custom_session)