← 返回首页
Provide a getting started doc for the API · python-gitlab/python-gitlab@2237d85 · GitHub
Skip to content

Navigation Menu

Toggle navigation
Sign in
Appearance settings
Search or jump to...

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted
Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Cancel Create saved search
Appearance settings
Resetting focus

Commit 2237d85

Browse files
Gauvain Pocentek
committed
Provide a getting started doc for the API
1 parent 64d6356 commit 2237d85

5 files changed

Lines changed: 125 additions & 7 deletions

File tree

‎docs/api-usage.rst‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
############################
2+
Getting started with the API
3+
############################
4+
5+
The ``gitlab`` package provides 3 basic types:
6+
7+
* ``gitlab.Gitlab`` is the primary class, handling the HTTP requests. It holds
8+
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.
14+
15+
``gitlab.Gitlab`` class
16+
=======================
17+
18+
To connect to a GitLab server, create a ``gitlab.Gitlab`` object:
19+
20+
.. code-block:: python
21+
22+
import gitlab
23+
24+
# private token authentication
25+
gl = gitlab.Gitlab('http://10.0.0.1', 'JVNSESs8EwWRx5yDxM5q')
26+
27+
# or username/password authentication
28+
gl = gitlab.Gitlab('http://10.0.0.1', email='jdoe', password='s3cr3t')
29+
30+
# make an API request to create the gl.user object. This is mandatory if you
31+
# use the username/password authentication.
32+
gl.auth()
33+
34+
You can also use configuration files to create ``gitlab.Gitlab`` objects:
35+
36+
.. code-block:: python
37+
38+
gl = gitlab.Gitlab.from_config('somewhere', ['/tmp/gl.cfg'])
39+
40+
See the :ref:`cli_configuration` section for more information about
41+
configuration files.
42+
43+
44+
Managers
45+
========
46+
47+
The ``gitlab.Gitlab`` class provides managers to access the GitLab resources.
48+
Each manager provides a set of methods to act on the resources. The available
49+
methods depend on the resource type. Resources are represented as
50+
``gitlab.GitlabObject``-derived objects.
51+
52+
Examples:
53+
54+
.. code-block:: python
55+
56+
# list all the projects
57+
projects = gl.projects.list()
58+
for project in projects:
59+
print(project)
60+
61+
# get the group with id == 2
62+
group = gl.groups.get(2)
63+
for group in groups:
64+
print()
65+
66+
# create a new user
67+
user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'}
68+
user = gl.users.create(user_data)
69+
print(user)
70+
71+
Some ``gitlab.GitlabObject`` classes also provide managers to access related
72+
GitLab resources:
73+
74+
.. code-block:: python
75+
76+
# list the issues for a project
77+
project = gl.projects.get(1)
78+
issues = project.issues.list()
79+
80+
Gitlab Objects
81+
==============
82+
83+
You can update or delete an object when it exists as a ``GitlabObject`` object:
84+
85+
.. code-block:: python
86+
87+
# update the attributes of a resource
88+
project = gl.projects.get(1)
89+
project.wall_enabled = False
90+
# don't forget to apply your changes on the server:
91+
project.save()
92+
93+
# delete the resource
94+
project.delete()
95+
96+
97+
Some ``GitlabObject``-derived classes provide additional methods, allowing more
98+
actions on the GitLab resources. For example:
99+
100+
.. code-block:: python
101+
102+
# get a tarball of the git repository
103+
project = gl.projects.get(1)
104+
project.archive()
105+
106+
Pagination
107+
==========
108+
109+
You can use pagination to go throught long lists:
110+
111+
.. code-block:: python
112+
113+
ten_first_groups = gl.groups.list(page=0, per_page=10)
114+
115+
Use the ``all`` parameter to get all the items:
116+
117+
.. code-block:: python
118+
119+
all_groups = gl.groups.list(all=True)

‎docs/api/gitlab.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
API/gitlab-module
2-
=================
1+
############################
2+
``gitlab`` API documentation
3+
############################
34

45
.. automodule:: gitlab
56
:members:

‎docs/cli.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
with GitLab servers. It uses a configuration file to define how to connect to
77
the servers.
88

9+
.. _cli_configuration:
10+
911
Configuration
1012
=============
1113

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Contents:
1313

1414
install
1515
cli
16-
usage
16+
api-usage
1717
api/gitlab
1818

1919

‎docs/usage.rst‎

Lines changed: 0 additions & 4 deletions
Load DiffThis file was deleted.

0 commit comments

Comments
 (0)

Footer

© 2026 GitHub, Inc.