FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Improve the docs to make v4 a first class citizen · ptomato/python-gitlab@60efc83 · GitHub

  1. ptomato
  2. python-gitlab

Repository navigation

Commit 60efc83

Browse files
Gauvain Pocentek
committed
Improve the docs to make v4 a first class citizen
1 parent 0268fc9 commit 60efc83

3 files changed

Lines changed: 85 additions & 29 deletions

File tree

‎docs/api-usage.rst‎

Lines changed: 75 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,38 @@
22
Getting started with the API
33
############################
44

5-
The ``gitlab`` package provides 3 base types:
5+
python-gitlab supports both GitLab v3 and v4 APIs.
6+
7+
v3 being deprecated by GitLab, its support in python-gitlab will be minimal.
8+
The development team will focus on v4.
9+
10+
v3 is still the default API used by python-gitlab, for compatibility reasons..
11+
12+
13+
Base types
14+
==========
15+
16+
The ``gitlab`` package provides some base types.
617

718
* ``gitlab.Gitlab`` is the primary class, handling the HTTP requests. It holds
819
the GitLab URL and authentication information.
9-
* ``gitlab.GitlabObject`` is the base class for all the GitLab objects. These
10-
objects provide an abstraction for GitLab resources (projects, groups, and so
11-
on).
12-
* ``gitlab.BaseManager`` is the base class for objects managers, providing the
13-
API to manipulate the resources and their attributes.
20+
21+
For v4 the following types are defined:
22+
23+
* ``gitlab.base.RESTObject`` is the base class for all the GitLab v4 objects.
24+
These objects provide an abstraction for GitLab resources (projects, groups,
25+
and so on).
26+
* ``gitlab.base.RESTManager`` is the base class for v4 objects managers,
27+
providing the API to manipulate the resources and their attributes.
28+
29+
For v3 the following types are defined:
30+
31+
* ``gitlab.base.GitlabObject`` is the base class for all the GitLab v3 objects.
32+
These objects provide an abstraction for GitLab resources (projects, groups,
33+
and so on).
34+
* ``gitlab.base.BaseManager`` is the base class for v3 objects managers,
35+
providing the API to manipulate the resources and their attributes.
36+
1437

1538
``gitlab.Gitlab`` class
1639
=======================
@@ -40,7 +63,9 @@ You can also use configuration files to create ``gitlab.Gitlab`` objects:
4063
See the :ref:`cli_configuration` section for more information about
4164
configuration files.
4265

43-
**GitLab v4 support**
66+
67+
API version
68+
===========
4469

4570
``python-gitlab`` uses the v3 GitLab API by default. Use the ``api_version``
4671
parameter to switch to v4:
@@ -53,15 +78,17 @@ parameter to switch to v4:
5378
5479
.. warning::
5580

56-
The v4 support is experimental.
81+
The python-gitlab API is not the same for v3 and v4. Make sure to read
82+
:ref:`switching_to_v4` before upgrading.
83+
84+
v4 will become the default in python-gitlab.
5785

5886
Managers
5987
========
6088

6189
The ``gitlab.Gitlab`` class provides managers to access the GitLab resources.
6290
Each manager provides a set of methods to act on the resources. The available
63-
methods depend on the resource type. Resources are represented as
64-
``gitlab.GitlabObject``-derived objects.
91+
methods depend on the resource type.
6592

6693
Examples:
6794

@@ -84,17 +111,22 @@ Examples:
84111
85112
The attributes of objects are defined upon object creation, and depend on the
86113
GitLab API itself. To list the available information associated with an object
87-
use the python introspection tools:
114+
use the python introspection tools for v3, or the ``attributes`` attribute for
115+
v4:
88116

89117
.. code-block:: python
90118
91119
project = gl.projects.get(1)
120+
121+
# v3
92122
print(vars(project))
93123
# or
94124
print(project.__dict__)
95125
96-
Some ``gitlab.GitlabObject`` classes also provide managers to access related
97-
GitLab resources:
126+
# v4
127+
print(project.attributes)
128+
129+
Some objects also provide managers to access related GitLab resources:
98130

99131
.. code-block:: python
100132
@@ -105,7 +137,7 @@ GitLab resources:
105137
Gitlab Objects
106138
==============
107139

108-
You can update or delete an object when it exists as a ``GitlabObject`` object:
140+
You can update or delete a remote object when it exists locally:
109141

110142
.. code-block:: python
111143
@@ -119,15 +151,31 @@ You can update or delete an object when it exists as a ``GitlabObject`` object:
119151
project.delete()
120152
121153
122-
Some ``GitlabObject``-derived classes provide additional methods, allowing more
123-
actions on the GitLab resources. For example:
154+
Some classes provide additional methods, allowing more actions on the GitLab
155+
resources. For example:
124156

125157
.. code-block:: python
126158
127159
# star a git repository
128160
project = gl.projects.get(1)
129161
project.star()
130162
163+
Lazy objects (v4 only)
164+
======================
165+
166+
To avoid useless calls to the server API, you can create lazy objects. These
167+
objects are created locally using a known ID, and give access to other managers
168+
and methods.
169+
170+
The following exemple will only make one API call to the GitLab server to star
171+
a project:
172+
173+
.. code-block:: python
174+
175+
# star a git repository
176+
project = gl.projects.get(1, lazy=True) # no API call
177+
project.star() # API call
178+
131179
Pagination
132180
==========
133181

@@ -142,16 +190,15 @@ listing methods support the ``page`` and ``per_page`` parameters:
142190

143191
The first page is page 1, not page 0.
144192

145-
146-
By default GitLab does not return the complete list of items. Use the ``all``
193+
By default GitLab does not return the complete list of items. Use the ``all``
147194
parameter to get all the items when using listing methods:
148195

149196
.. code-block:: python
150197
151198
all_groups = gl.groups.list(all=True)
152199
all_owned_projects = gl.projects.owned(all=True)
153200
154-
.. note::
201+
.. warning::
155202

156203
python-gitlab will iterate over the list by calling the corresponding API
157204
multiple times. This might take some time if you have a lot of items to
@@ -160,6 +207,15 @@ parameter to get all the items when using listing methods:
160207
use ``safe_all=True`` instead to stop pagination automatically if the
161208
recursion limit is hit.
162209

210+
With v4, ``list()`` methods can also return a generator object which will
211+
handle the next calls to the API when required:
212+
213+
.. code-block:: python
214+
215+
items = gl.groups.list(as_list=False)
216+
for item in items:
217+
print(item.attributes)
218+
163219
Sudo
164220
====
165221

‎docs/cli.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ Content
2828
-------
2929

3030
The configuration file uses the ``INI`` format. It contains at least a
31-
``[global]`` section, and a new section for each GitLab server. For example:
31+
``[global]`` section, and a specific section for each GitLab server. For
32+
example:
3233

3334
.. code-block:: ini
3435
@@ -98,7 +99,7 @@ CLI
9899
Objects and actions
99100
-------------------
100101

101-
The ``gitlab`` command expects two mandatory arguments. This first one is the
102+
The ``gitlab`` command expects two mandatory arguments. The first one is the
102103
type of object that you want to manipulate. The second is the action that you
103104
want to perform. For example:
104105

@@ -140,8 +141,8 @@ These options must be defined before the mandatory arguments.
140141
Output format. Defaults to a custom format. Can also be ``yaml`` or ``json``.
141142

142143
``--fields``, ``-f``
143-
Comma-separated list of fields to display (``yaml`` and ``json`` formats
144-
only). If not used, all the object fields are displayed.
144+
Comma-separated list of fields to display (``yaml`` and ``json`` output
145+
formats only). If not used, all the object fields are displayed.
145146

146147
Example:
147148

‎docs/switching-to-v4.rst‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _switching_to_v4:
2+
13
##########################
24
Switching to GtiLab API v4
35
##########################
@@ -10,15 +12,12 @@ GitLab will stop supporting the v3 API soon, and you should consider switching
1012
to v4 if you use a recent version of GitLab (>= 9.0), or if you use
1113
http://gitlab.com.
1214

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-
1715

1816
Using the v4 API
1917
================
2018

21-
To use the new v4 API, explicitly use it in the ``Gitlab`` constructor:
19+
To use the new v4 API, explicitly define ``api_version` `in the ``Gitlab``
20+
constructor:
2221

2322
.. code-block:: python
2423
@@ -79,7 +78,7 @@ following important changes in the python API:
7978
calls.
8079

8180
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
81+
``lazy=True`` parameter. This creates shallow objects that provide usual
8382
managers.
8483

8584
The following v3 code:

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL