Skip to content

Commit 22ae101

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

File tree

3 files changed

+164
-160
lines changed

3 files changed

+164
-160
lines changed

‎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)