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
|
.. _switching_to_v4:
##########################
Switching to GitLab API v4
##########################
GitLab provides a new API version (v4) since its 9.0 release. ``python-gitlab``
provides support for this new version, but the python API has been modified to
solve some problems with the existing one.
GitLab does not support the v3 API anymore, and you should consider switching
to v4 if you use a recent version of GitLab (>= 9.0), or if you use
https://gitlab.com.
Using the v4 API
================
python-gitlab uses the v4 API by default since the 1.3.0 release. If you are
migrating from an older release, make sure that you remove the ``api_version``
definition in you constructors and configuration file:
The following examples are **not valid** anymore:
.. code-block:: python
gl = gitlab.Gitlab(..., api_version=3)
.. code-block:: ini
[my_gitlab]
...
api_version = 3
Changes between v3 and v4 API
=============================
For a list of GitLab (upstream) API changes, see
https://docs.gitlab.com/ce/api/v3_to_v4.html.
The ``python-gitlab`` API reflects these changes. But also consider the
following important changes in the python API:
* managers and objects don't inherit from ``GitlabObject`` and ``BaseManager``
anymore. They inherit from :class:`~gitlab.base.RESTManager` and
:class:`~gitlab.base.RESTObject`.
* You should only use the managers to perform CRUD operations.
The following v3 code:
.. code-block:: python
gl = gitlab.Gitlab(...)
p = Project(gl, project_id)
Should be replaced with:
.. code-block:: python
gl = gitlab.Gitlab(...)
p = gl.projects.get(project_id)
* Listing methods (``manager.list()`` for instance) can now return generators
(:class:`~gitlab.base.RESTObjectList`). They handle the calls to the API when
needed to fetch new items.
By default you will still get lists. To get generators use ``as_list=False``:
.. code-block:: python
all_projects_g = gl.projects.list(as_list=False)
* The "nested" managers (for instance ``gl.project_issues`` or
``gl.group_members``) are not available anymore. Their goal was to provide a
direct way to manage nested objects, and to limit the number of needed API
calls.
To limit the number of API calls, you can now use ``get()`` methods with the
``lazy=True`` parameter. This creates shallow objects that provide usual
managers.
The following v3 code:
.. code-block:: python
issues = gl.project_issues.list(project_id=project_id)
Should be replaced with:
.. code-block:: python
issues = gl.projects.get(project_id, lazy=True).issues.list()
This will make only one API call, instead of two if ``lazy`` is not used.
* The following :class:`~gitlab.Gitlab` methods should not be used anymore for
v4:
+ ``list()``
+ ``get()``
+ ``create()``
+ ``update()``
+ ``delete()``
* If you need to perform HTTP requests to the GitLab server (which you
shouldn't), you can use the following :class:`~gitlab.Gitlab` methods:
+ :attr:`~gitlab.Gitlab.http_request`
+ :attr:`~gitlab.Gitlab.http_get`
+ :attr:`~gitlab.Gitlab.http_list`
+ :attr:`~gitlab.Gitlab.http_post`
+ :attr:`~gitlab.Gitlab.http_put`
+ :attr:`~gitlab.Gitlab.http_delete`
|
