Getting started with the API¶

gitlab.Gitlab class¶

To connect to a GitLab server, create a gitlab.Gitlab object:

You can also use configuration files to create gitlab.Gitlab objects:

See the 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.

Examples:

You can list the mandatory and optional attributes for object creation and update with the manager’s get_create_attrs() and get_update_attrs() methods. They return 2 tuples, the first one is the list of mandatory attributes, the second one is the list of optional attribute:

The attributes of objects are defined upon object creation, and depend on the GitLab API itself. To list the available information associated with an object use the attributes attribute:

Some objects also provide managers to access related GitLab resources:

python-gitlab allows to send any data to the GitLab server when making queries. In case of invalid or missing arguments python-gitlab will raise an exception with the GitLab server error message:

You can use the query_parameters argument to send arguments that would conflict with python or python-gitlab when using them as kwargs:

Gitlab Objects¶

You can update or delete a remote object when it exists locally:

Some classes provide additional methods, allowing more actions on the GitLab resources. For example:

Base types¶

The gitlab package provides some base types.

• gitlab.Gitlab is the primary class, handling the HTTP requests. It holds the GitLab URL and authentication information.

• gitlab.base.RESTObject is the base class for all the GitLab v4 objects. These objects provide an abstraction for GitLab resources (projects, groups, and so on).

• gitlab.base.RESTManager is the base class for v4 objects managers, providing the API to manipulate the resources and their attributes.

Lazy objects¶

To avoid useless API calls to the server you can create lazy objects. These objects are created locally using a known ID, and give access to other managers and methods.

The following example will only make one API call to the GitLab server to star a project (the previous example used 2 API calls):

Pagination¶

You can use pagination to iterate over long lists. All the Gitlab objects listing methods support the page and per_page parameters:

By default GitLab does not return the complete list of items. Use the all parameter to get all the items when using listing methods:

You can define the per_page value globally to avoid passing it to every list() method call:

list() methods can also return a generator object which will handle the next calls to the API when required. This is the recommended way to iterate through a large number of items:

The generator exposes extra listing information as received from the server:

• current_page: current page number (first page is 1)

• prev_page: if None the current page is the first one

• next_page: if None the current page is the last one

• per_page: number of items per page

• total_pages: total number of pages available

• total: total number of items in the list

Sudo¶

If you have the administrator status, you can use sudo to act as another user. For example:

Advanced HTTP configuration¶

python-gitlab relies on requests Session objects to perform all the HTTP requests to the Gitlab servers.

You can provide your own Session object with custom configuration when you create a Gitlab object.