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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
############################
Getting started with the API
############################
The ``gitlab`` package provides 3 basic types:
* ``gitlab.Gitlab`` is the primary class, handling the HTTP requests. It holds
the GitLab URL and authentication information.
* ``gitlab.GitlabObject`` is the base class for all the GitLab objects. These
objects provide an abstraction for GitLab resources (projects, groups, and so
on).
* ``gitlab.BaseManager`` is the base class for objects managers, providing the
API to manipulate the resources and their attributes.
``gitlab.Gitlab`` class
=======================
To connect to a GitLab server, create a ``gitlab.Gitlab`` object:
.. code-block:: python
import gitlab
# private token authentication
gl = gitlab.Gitlab('http://10.0.0.1', 'JVNSESs8EwWRx5yDxM5q')
# oauth authentication
gl = gitlab.Gitlab('http://10.0.0.1', my_oauth2_token)
# or username/password authentication
gl = gitlab.Gitlab('http://10.0.0.1', email='jdoe', password='s3cr3t')
# make an API request to create the gl.user object. This is mandatory if you
# use the username/password authentication.
gl.auth()
You can also use configuration files to create ``gitlab.Gitlab`` objects:
.. code-block:: python
gl = gitlab.Gitlab.from_config('somewhere', ['/tmp/gl.cfg'])
See the :ref:`cli_configuration` section for more information about
configuration files.
Managers
========
The ``gitlab.Gitlab`` class provides managers to access the GitLab resources.
Each manager provides a set of methods to act on the resources. The available
methods depend on the resource type. Resources are represented as
``gitlab.GitlabObject``-derived objects.
Examples:
.. code-block:: python
# list all the projects
projects = gl.projects.list()
for project in projects:
print(project)
# get the group with id == 2
group = gl.groups.get(2)
for group in groups:
print()
# create a new user
user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'}
user = gl.users.create(user_data)
print(user)
Some ``gitlab.GitlabObject`` classes also provide managers to access related
GitLab resources:
.. code-block:: python
# list the issues for a project
project = gl.projects.get(1)
issues = project.issues.list()
Gitlab Objects
==============
You can update or delete an object when it exists as a ``GitlabObject`` object:
.. code-block:: python
# update the attributes of a resource
project = gl.projects.get(1)
project.wall_enabled = False
# don't forget to apply your changes on the server:
project.save()
# delete the resource
project.delete()
Some ``GitlabObject``-derived classes provide additional methods, allowing more
actions on the GitLab resources. For example:
.. code-block:: python
# star a git repository
project = gl.projects.get(1)
project.star()
Pagination
==========
You can use pagination to iterate over long lists. All the Gitlab objects
listing methods support the ``page`` and ``per_page`` parameters:
.. code-block:: python
ten_first_groups = gl.groups.list(page=0, per_page=10)
By default GitLab does not return the complete list of items. Use the ``all``
parameter to get all the items when using listing methods:
.. code-block:: python
all_groups = gl.groups.list(all=True)
all_owned_projects = gl.projects.owned(all=True)
.. note::
python-gitlab will iterate over the list by calling the correspnding API
multiple times. This might take some time if you have a lot of items to
retrieve. This might also consume a lot of memory as all the items will be
stored in RAM.
Sudo
====
If you have the administrator status, you can use ``sudo`` to act as another
user. For example:
.. code-block:: python
p = gl.projects.create({'name': 'awesome_project'}, sudo='user1')
|
