← 返回首页
docs(api): add separate section for advanced usage · python-gitlab/python-gitlab@22ae101 · GitHub
Skip to content

Navigation Menu

Toggle navigation
Sign in
Appearance settings
Search or jump to...

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted
Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Cancel Create saved search
Appearance settings
Resetting focus

Commit 22ae101

Browse files
nejch
authored and
JohnVillalovos
committed
docs(api): add separate section for advanced usage
1 parent f9b7c7b commit 22ae101

3 files changed

Lines changed: 164 additions & 160 deletions

File tree

‎docs/api-usage-advanced.rst‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
##############
2+
Advanced usage
3+
##############
4+
5+
Using a custom session
6+
----------------------
7+
8+
python-gitlab relies on ``requests.Session`` objects to perform all the
9+
HTTP requests to the Gitlab servers.
10+
11+
You can provide your own ``Session`` object with custom configuration when
12+
you create a ``Gitlab`` object.
13+
14+
Context manager
15+
---------------
16+
17+
You can use ``Gitlab`` objects as context managers. This makes sure that the
18+
``requests.Session`` object associated with a ``Gitlab`` instance is always
19+
properly closed when you exit a ``with`` block:
20+
21+
.. code-block:: python
22+
23+
with gitlab.Gitlab(host, token) as gl:
24+
gl.projects.list()
25+
26+
.. warning::
27+
28+
The context manager will also close the custom ``Session`` object you might
29+
have used to build the ``Gitlab`` instance.
30+
31+
Proxy configuration
32+
-------------------
33+
34+
The following sample illustrates how to define a proxy configuration when using
35+
python-gitlab:
36+
37+
.. code-block:: python
38+
39+
import os
40+
import gitlab
41+
import requests
42+
43+
session = requests.Session()
44+
session.proxies = {
45+
'https': os.environ.get('https_proxy'),
46+
'http': os.environ.get('http_proxy'),
47+
}
48+
gl = gitlab.gitlab(url, token, api_version=4, session=session)
49+
50+
Reference:
51+
https://requests.readthedocs.io/en/latest/user/advanced/#proxies
52+
53+
SSL certificate verification
54+
----------------------------
55+
56+
python-gitlab relies on the CA certificate bundle in the `certifi` package
57+
that comes with the requests library.
58+
59+
If you need python-gitlab to use your system CA store instead, you can provide
60+
the path to the CA bundle in the `REQUESTS_CA_BUNDLE` environment variable.
61+
62+
Reference:
63+
https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification
64+
65+
Client side certificate
66+
-----------------------
67+
68+
The following sample illustrates how to use a client-side certificate:
69+
70+
.. code-block:: python
71+
72+
import gitlab
73+
import requests
74+
75+
session = requests.Session()
76+
session.cert = ('/path/to/client.cert', '/path/to/client.key')
77+
gl = gitlab.gitlab(url, token, api_version=4, session=session)
78+
79+
Reference:
80+
https://requests.readthedocs.io/en/latest/user/advanced/#client-side-certificates
81+
82+
Rate limits
83+
-----------
84+
85+
python-gitlab obeys the rate limit of the GitLab server by default. On
86+
receiving a 429 response (Too Many Requests), python-gitlab sleeps for the
87+
amount of time in the Retry-After header that GitLab sends back. If GitLab
88+
does not return a response with the Retry-After header, python-gitlab will
89+
perform an exponential backoff.
90+
91+
If you don't want to wait, you can disable the rate-limiting feature, by
92+
supplying the ``obey_rate_limit`` argument.
93+
94+
.. code-block:: python
95+
96+
import gitlab
97+
import requests
98+
99+
gl = gitlab.gitlab(url, token, api_version=4)
100+
gl.projects.list(all=True, obey_rate_limit=False)
101+
102+
If you do not disable the rate-limiting feature, you can supply a custom value
103+
for ``max_retries``; by default, this is set to 10. To retry without bound when
104+
throttled, you can set this parameter to -1. This parameter is ignored if
105+
``obey_rate_limit`` is set to ``False``.
106+
107+
.. code-block:: python
108+
109+
import gitlab
110+
import requests
111+
112+
gl = gitlab.gitlab(url, token, api_version=4)
113+
gl.projects.list(all=True, max_retries=12)
114+
115+
.. warning::
116+
117+
You will get an Exception, if you then go over the rate limit of your GitLab instance.
118+
119+
Transient errors
120+
----------------
121+
122+
GitLab server can sometimes return a transient HTTP error.
123+
python-gitlab can automatically retry in such case, when
124+
``retry_transient_errors`` argument is set to ``True``. When enabled,
125+
HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway),
126+
503 (Service Unavailable), and 504 (Gateway Timeout) are retried. It will retry until reaching
127+
the `max_retries` value. By default, `retry_transient_errors` is set to `False` and an exception
128+
is raised for these errors.
129+
130+
.. code-block:: python
131+
132+
import gitlab
133+
import requests
134+
135+
gl = gitlab.gitlab(url, token, api_version=4)
136+
gl.projects.list(all=True, retry_transient_errors=True)
137+
138+
The default ``retry_transient_errors`` can also be set on the ``Gitlab`` object
139+
and overridden by individual API calls.
140+
141+
.. code-block:: python
142+
143+
import gitlab
144+
import requests
145+
gl = gitlab.gitlab(url, token, api_version=4, retry_transient_errors=True)
146+
gl.projects.list(all=True) # retries due to default value
147+
gl.projects.list(all=True, retry_transient_errors=False) # does not retry
148+
149+
Timeout
150+
-------
151+
152+
python-gitlab will by default use the ``timeout`` option from its configuration
153+
for all requests. This is passed downwards to the ``requests`` module at the
154+
time of making the HTTP request. However if you would like to override the
155+
global timeout parameter for a particular call, you can provide the ``timeout``
156+
parameter to that API invocation:
157+
158+
.. code-block:: python
159+
160+
import gitlab
161+
162+
gl = gitlab.gitlab(url, token, api_version=4)
163+
gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)

‎docs/api-usage.rst‎

Lines changed: 0 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -345,166 +345,6 @@ user. For example:
345345
346346
p = gl.projects.create({'name': 'awesome_project'}, sudo='user1')
347347
348-
Advanced HTTP configuration
349-
===========================
350-
351-
python-gitlab relies on ``requests`` ``Session`` objects to perform all the
352-
HTTP requests to the Gitlab servers.
353-
354-
You can provide your own ``Session`` object with custom configuration when
355-
you create a ``Gitlab`` object.
356-
357-
Context manager
358-
---------------
359-
360-
You can use ``Gitlab`` objects as context managers. This makes sure that the
361-
``requests.Session`` object associated with a ``Gitlab`` instance is always
362-
properly closed when you exit a ``with`` block:
363-
364-
.. code-block:: python
365-
366-
with gitlab.Gitlab(host, token) as gl:
367-
gl.projects.list()
368-
369-
.. warning::
370-
371-
The context manager will also close the custom ``Session`` object you might
372-
have used to build the ``Gitlab`` instance.
373-
374-
Proxy configuration
375-
-------------------
376-
377-
The following sample illustrates how to define a proxy configuration when using
378-
python-gitlab:
379-
380-
.. code-block:: python
381-
382-
import os
383-
import gitlab
384-
import requests
385-
386-
session = requests.Session()
387-
session.proxies = {
388-
'https': os.environ.get('https_proxy'),
389-
'http': os.environ.get('http_proxy'),
390-
}
391-
gl = gitlab.gitlab(url, token, api_version=4, session=session)
392-
393-
Reference:
394-
https://requests.readthedocs.io/en/latest/user/advanced/#proxies
395-
396-
SSL certificate verification
397-
----------------------------
398-
399-
python-gitlab relies on the CA certificate bundle in the `certifi` package
400-
that comes with the requests library.
401-
402-
If you need python-gitlab to use your system CA store instead, you can provide
403-
the path to the CA bundle in the `REQUESTS_CA_BUNDLE` environment variable.
404-
405-
Reference:
406-
https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification
407-
408-
Client side certificate
409-
-----------------------
410-
411-
The following sample illustrates how to use a client-side certificate:
412-
413-
.. code-block:: python
414-
415-
import gitlab
416-
import requests
417-
418-
session = requests.Session()
419-
session.cert = ('/path/to/client.cert', '/path/to/client.key')
420-
gl = gitlab.gitlab(url, token, api_version=4, session=session)
421-
422-
Reference:
423-
https://requests.readthedocs.io/en/latest/user/advanced/#client-side-certificates
424-
425-
Rate limits
426-
-----------
427-
428-
python-gitlab obeys the rate limit of the GitLab server by default. On
429-
receiving a 429 response (Too Many Requests), python-gitlab sleeps for the
430-
amount of time in the Retry-After header that GitLab sends back. If GitLab
431-
does not return a response with the Retry-After header, python-gitlab will
432-
perform an exponential backoff.
433-
434-
If you don't want to wait, you can disable the rate-limiting feature, by
435-
supplying the ``obey_rate_limit`` argument.
436-
437-
.. code-block:: python
438-
439-
import gitlab
440-
import requests
441-
442-
gl = gitlab.gitlab(url, token, api_version=4)
443-
gl.projects.list(all=True, obey_rate_limit=False)
444-
445-
If you do not disable the rate-limiting feature, you can supply a custom value
446-
for ``max_retries``; by default, this is set to 10. To retry without bound when
447-
throttled, you can set this parameter to -1. This parameter is ignored if
448-
``obey_rate_limit`` is set to ``False``.
449-
450-
.. code-block:: python
451-
452-
import gitlab
453-
import requests
454-
455-
gl = gitlab.gitlab(url, token, api_version=4)
456-
gl.projects.list(all=True, max_retries=12)
457-
458-
.. warning::
459-
460-
You will get an Exception, if you then go over the rate limit of your GitLab instance.
461-
462-
Transient errors
463-
----------------
464-
465-
GitLab server can sometimes return a transient HTTP error.
466-
python-gitlab can automatically retry in such case, when
467-
``retry_transient_errors`` argument is set to ``True``. When enabled,
468-
HTTP error codes 500 (Internal Server Error), 502 (502 Bad Gateway),
469-
503 (Service Unavailable), and 504 (Gateway Timeout) are retried. It will retry until reaching
470-
the `max_retries` value. By default, `retry_transient_errors` is set to `False` and an exception
471-
is raised for these errors.
472-
473-
.. code-block:: python
474-
475-
import gitlab
476-
import requests
477-
478-
gl = gitlab.gitlab(url, token, api_version=4)
479-
gl.projects.list(all=True, retry_transient_errors=True)
480-
481-
The default ``retry_transient_errors`` can also be set on the ``Gitlab`` object
482-
and overridden by individual API calls.
483-
484-
.. code-block:: python
485-
486-
import gitlab
487-
import requests
488-
gl = gitlab.gitlab(url, token, api_version=4, retry_transient_errors=True)
489-
gl.projects.list(all=True) # retries due to default value
490-
gl.projects.list(all=True, retry_transient_errors=False) # does not retry
491-
492-
Timeout
493-
-------
494-
495-
python-gitlab will by default use the ``timeout`` option from it's configuration
496-
for all requests. This is passed downwards to the ``requests`` module at the
497-
time of making the HTTP request. However if you would like to override the
498-
global timeout parameter for a particular call, you can provide the ``timeout``
499-
parameter to that API invocation:
500-
501-
.. code-block:: python
502-
503-
import gitlab
504-
505-
gl = gitlab.gitlab(url, token, api_version=4)
506-
gl.projects.import_github(ACCESS_TOKEN, 123456, "root", timeout=120.0)
507-
508348
.. _object_attributes:
509349

510350
Attributes in updated objects

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
cli-usage
88
api-usage
9+
api-usage-advanced
910
cli-examples
1011
api-objects
1112
api/gitlab

0 commit comments

Comments
 (0)

Footer

© 2026 GitHub, Inc.