1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
##############
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
with gitlab.Gitlab(host, token) as gl:
gl.projects.list()
.. 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
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
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
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
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
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``.
.. code-block:: python
import gitlab
import requests
gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.list(get_all=True, max_retries=12)
.. 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
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.
.. code-block:: python
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
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
import gitlab
gl = gitlab.gitlab(url, token, api_version=4)
gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)
Typing
------
Generally, ``python-gitlab`` is a fully typed package. However, currently you may still
need to do some
`type narrowing <https://mypy.readthedocs.io/en/stable/type_narrowing.html#type-narrowing>`_
on your own, such as for nested API responses and ``Union`` return types. For example:
.. code-block:: python
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)
|
