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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
##############
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 a custom session to create ``gitlab.Gitlab`` objects:
.. code-block:: python
import gitlab
import requests
session = requests.Session()
gl = gitlab.Gitlab(session=session)
# or when instantiating from configuration files
gl = gitlab.Gitlab.from_config('somewhere', ['/tmp/gl.cfg'], session=session)
Reference:
https://requests.readthedocs.io/en/latest/user/advanced/#session-objects
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.
netrc authentication
--------------------
python-gitlab reads credentials from ``.netrc`` files via the ``requests`` backend by default,
which may override authentication headers you set on your client.
For more granular control, you can disable this `Using a custom session`_
and explicitly setting ``trust_env=False`` as described in the ``requests`` documentation.
.. code-block:: python
import gitlab
import requests
session = requests.Session(trust_env=False)
gl = gitlab.Gitlab(session=session)
Reference:
https://requests.readthedocs.io/en/latest/user/authentication/#netrc-authentication
Proxy configuration
-------------------
python-gitlab accepts the standard ``http_proxy``, ``https_proxy`` and ``no_proxy``
environment variables via the ``requests`` backend. Uppercase variables are also supported.
For more granular control, you can also explicitly set proxies by `Using a custom session`_
as described in the ``requests`` documentation.
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), 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 <https://gitlab.com/gitlab-org/gitlab/-/blob/443c12cf3b238385db728f03b2cdbb4f17c70292/lib/api/api.rb#L111>`__.
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)
|
