Skip to content

Commit 3ccdec0

Browse files
author
Gauvain Pocentek
committed
Merge branch 'rework_api'
2 parents e87835f + 2816c1a commit 3ccdec0

27 files changed

+4359
-2222
lines changed

‎.travis.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ addons:
1010
language: python
1111
python: 2.7
1212
env:
13-
- TOX_ENV=py36
1413
- TOX_ENV=py35
1514
- TOX_ENV=py34
1615
- TOX_ENV=py27

‎MANIFEST.in‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
include COPYING AUTHORS ChangeLog requirements.txt test-requirements.txt rtd-requirements.txt
1+
include COPYING AUTHORS ChangeLog.rst RELEASE_NOTES.rst requirements.txt test-requirements.txt rtd-requirements.txt
22
include tox.ini .testr.conf .travis.yml
33
recursive-include tools *
44
recursive-include docs *j2 *.py *.rst api/*.rst Makefile make.bat

‎docs/api/gitlab.rst‎

Lines changed: 48 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,48 @@
11
gitlab package
22
==============
33

4-
Module contents
5-
---------------
4+
Subpackages
5+
-----------
66

7-
.. automodule:: gitlab
7+
.. toctree::
8+
9+
gitlab.v3
10+
gitlab.v4
11+
12+
Submodules
13+
----------
14+
15+
gitlab.base module
16+
------------------
17+
18+
.. automodule:: gitlab.base
819
:members:
920
:undoc-members:
1021
:show-inheritance:
11-
:exclude-members: Hook, UserProject, Group, Issue, Team, User,
12-
all_projects, owned_projects, search_projects
1322

14-
gitlab.base
15-
-----------
23+
gitlab.cli module
24+
-----------------
1625

17-
.. automodule:: gitlab.base
26+
.. automodule:: gitlab.cli
1827
:members:
1928
:undoc-members:
2029
:show-inheritance:
2130

22-
gitlab.v3.objects module
23-
------------------------
31+
gitlab.config module
32+
--------------------
2433

25-
.. automodule:: gitlab.v3.objects
34+
.. automodule:: gitlab.config
2635
:members:
2736
:undoc-members:
2837
:show-inheritance:
29-
:exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
30-
Label, Member, MergeRequest, Milestone, Note, Snippet,
31-
Tag, canGet, canList, canUpdate, canCreate, canDelete,
32-
requiredUrlAttrs, requiredListAttrs, optionalListAttrs,
33-
optionalGetAttrs, requiredGetAttrs, requiredDeleteAttrs,
34-
requiredCreateAttrs, optionalCreateAttrs,
35-
requiredUpdateAttrs, optionalUpdateAttrs, getRequiresId,
36-
shortPrintAttr, idAttr
3738

38-
gitlab.v4.objects module
39-
------------------------
39+
gitlab.const module
40+
-------------------
4041

41-
.. automodule:: gitlab.v4.objects
42+
.. automodule:: gitlab.const
4243
:members:
4344
:undoc-members:
4445
:show-inheritance:
45-
:exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
46-
Label, Member, MergeRequest, Milestone, Note, Snippet,
47-
Tag, canGet, canList, canUpdate, canCreate, canDelete,
48-
requiredUrlAttrs, requiredListAttrs, optionalListAttrs,
49-
optionalGetAttrs, requiredGetAttrs, requiredDeleteAttrs,
50-
requiredCreateAttrs, optionalCreateAttrs,
51-
requiredUpdateAttrs, optionalUpdateAttrs, getRequiresId,
52-
shortPrintAttr, idAttr
5346

5447
gitlab.exceptions module
5548
------------------------
@@ -58,3 +51,28 @@ gitlab.exceptions module
5851
:members:
5952
:undoc-members:
6053
:show-inheritance:
54+
55+
gitlab.mixins module
56+
--------------------
57+
58+
.. automodule:: gitlab.mixins
59+
:members:
60+
:undoc-members:
61+
:show-inheritance:
62+
63+
gitlab.utils module
64+
-------------------
65+
66+
.. automodule:: gitlab.utils
67+
:members:
68+
:undoc-members:
69+
:show-inheritance:
70+
71+
72+
Module contents
73+
---------------
74+
75+
.. automodule:: gitlab
76+
:members:
77+
:undoc-members:
78+
:show-inheritance:

‎docs/api/gitlab.v3.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gitlab.v3 package
2+
=================
3+
4+
Submodules
5+
----------
6+
7+
gitlab.v3.objects module
8+
------------------------
9+
10+
.. automodule:: gitlab.v3.objects
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
16+
Module contents
17+
---------------
18+
19+
.. automodule:: gitlab.v3
20+
:members:
21+
:undoc-members:
22+
:show-inheritance:

‎docs/api/gitlab.v4.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
gitlab.v4 package
2+
=================
3+
4+
Submodules
5+
----------
6+
7+
gitlab.v4.objects module
8+
------------------------
9+
10+
.. automodule:: gitlab.v4.objects
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
16+
Module contents
17+
---------------
18+
19+
.. automodule:: gitlab.v4
20+
:members:
21+
:undoc-members:
22+
:show-inheritance:

‎docs/api/modules.rst‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/ext/docstrings.py‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010

1111

1212
def classref(value, short=True):
13+
return value
14+
1315
if not inspect.isclass(value):
1416
return ':class:%s' % value
1517
tilde = '~' if short else ''
@@ -46,8 +48,13 @@ def _build_doc(self, tmpl, **kwargs):
4648

4749
return output.split('\n')
4850

49-
def __init__(self, *args, **kwargs):
50-
super(GitlabDocstring, self).__init__(*args, **kwargs)
51+
def __init__(self, docstring, config=None, app=None, what='', name='',
52+
obj=None, options=None):
53+
super(GitlabDocstring, self).__init__(docstring, config, app, what,
54+
name, obj, options)
55+
56+
if name and name.startswith('gitlab.v4.objects'):
57+
return
5158

5259
if getattr(self._obj, '__name__', None) == 'Gitlab':
5360
mgrs = []
@@ -57,9 +64,12 @@ def __init__(self, *args, **kwargs):
5764
mgrs.append(item)
5865
self._parsed_lines.extend(self._build_doc('gl_tmpl.j2',
5966
mgrs=sorted(mgrs)))
67+
68+
# BaseManager
6069
elif hasattr(self._obj, 'obj_cls') and self._obj.obj_cls is not None:
6170
self._parsed_lines.extend(self._build_doc('manager_tmpl.j2',
6271
cls=self._obj.obj_cls))
72+
# GitlabObject
6373
elif hasattr(self._obj, 'canUpdate') and self._obj.canUpdate:
6474
self._parsed_lines.extend(self._build_doc('object_tmpl.j2',
6575
obj=self._obj))

‎docs/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ Contents:
1414
install
1515
cli
1616
api-usage
17+
switching-to-v4
1718
api-objects
18-
upgrade-from-0.10
19-
api/modules
19+
api/gitlab
2020
release_notes
2121
changelog
2222

‎docs/switching-to-v4.rst‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
##########################
2+
Switching to GtiLab API v4
3+
##########################
4+
5+
GitLab provides a new API version (v4) since its 9.0 release. ``python-gitlab``
6+
provides support for this new version, but the python API has been modified to
7+
solve some problems with the existing one.
8+
9+
GitLab will stop supporting the v3 API soon, and you should consider switching
10+
to v4 if you use a recent version of GitLab (>= 9.0), or if you use
11+
http://gitlab.com.
12+
13+
The new v4 API is available in the `rework_api branch on github
14+
<https://github.com/python-gitlab/python-gitlab/tree/rework_api>`_, and will be
15+
released soon.
16+
17+
18+
Using the v4 API
19+
================
20+
21+
To use the new v4 API, explicitly use it in the ``Gitlab`` constructor:
22+
23+
.. code-block:: python
24+
25+
gl = gitlab.Gitlab(..., api_version=4)
26+
27+
28+
If you use the configuration file, also explicitly define the version:
29+
30+
.. code-block:: ini
31+
32+
[my_gitlab]
33+
...
34+
api_version = 4
35+
36+
37+
Changes between v3 and v4 API
38+
=============================
39+
40+
For a list of GtiLab (upstream) API changes, see
41+
https://docs.gitlab.com/ce/api/v3_to_v4.html.
42+
43+
The ``python-gitlab`` API reflects these changes. But also consider the
44+
following important changes in the python API:
45+
46+
* managers and objects don't inherit from ``GitlabObject`` and ``BaseManager``
47+
anymore. They inherit from :class:`~gitlab.base.RESTManager` and
48+
:class:`~gitlab.base.RESTObject`.
49+
50+
* You should only use the managers to perform CRUD operations.
51+
52+
The following v3 code:
53+
54+
.. code-block:: python
55+
56+
gl = gitlab.Gitlab(...)
57+
p = Project(gl, project_id)
58+
59+
Should be replaced with:
60+
61+
.. code-block:: python
62+
63+
gl = gitlab.Gitlab(...)
64+
p = gl.projects.get(project_id)
65+
66+
* Listing methods (``manager.list()`` for instance) can now return generators
67+
(:class:`~gitlab.base.RESTObjectList`). They handle the calls to the API when
68+
needed to fetch new items.
69+
70+
By default you will still get lists. To get generators use ``as_list=False``:
71+
72+
.. code-block:: python
73+
74+
all_projects_g = gl.projects.list(as_list=False)
75+
76+
* The "nested" managers (for instance ``gl.project_issues`` or
77+
``gl.group_members``) are not available anymore. Their goal was to provide a
78+
direct way to manage nested objects, and to limit the number of needed API
79+
calls.
80+
81+
To limit the number of API calls, you can now use ``get()`` methods with the
82+
``lazy=True`` parameter. This creates shallow objects that provide usual
83+
managers.
84+
85+
The following v3 code:
86+
87+
.. code-block:: python
88+
89+
issues = gl.project_issues.list(project_id=project_id)
90+
91+
Should be replaced with:
92+
93+
.. code-block:: python
94+
95+
issues = gl.projects.get(project_id, lazy=True).issues.list()
96+
97+
This will make only one API call, instead of two if ``lazy`` is not used.
98+
99+
* The :class:`~gitlab.Gitlab` folowwing methods should not be used anymore for
100+
v4:
101+
102+
+ ``list()``
103+
+ ``get()``
104+
+ ``create()``
105+
+ ``update()``
106+
+ ``delete()``
107+
108+
* If you need to perform HTTP requests to the GitLab server (which you
109+
shouldn't), you can use the following :class:`~gitlab.Gitlab` methods:
110+
111+
+ :attr:`~gitlab.Gitlab.http_request`
112+
+ :attr:`~gitlab.Gitlab.http_get`
113+
+ :attr:`~gitlab.Gitlab.http_list`
114+
+ :attr:`~gitlab.Gitlab.http_post`
115+
+ :attr:`~gitlab.Gitlab.http_put`
116+
+ :attr:`~gitlab.Gitlab.http_delete`

0 commit comments

Comments
 (0)