API reference (gitlab package)

Submodules

gitlab.base module

class gitlab.base.RESTManager(gl: gitlab.client.Gitlab, parent: Optional[gitlab.base.RESTObject] = None)

Bases: object

Base class for CRUD operations on objects.

Derived class must define _path and _obj_cls.

_path: Base URL path on which requests will be sent (e.g. ‘/projects’) _obj_cls: The class of objects that will be created

gitlab: gitlab.client.Gitlab
property parent_attrs
property path
class gitlab.base.RESTObject(manager: gitlab.base.RESTManager, attrs: Dict[str, Any])

Bases: object

Represents an object built from server data.

It holds the attributes know from the server, and the updated attributes in another. This allows smart updates, if the object allows it.

You can redefine _id_attr in child classes to specify which attribute must be used as uniq ID. None means that the object can be updated without ID in the url.

property attributes
get_id()

Returns the id of the resource.

manager: gitlab.base.RESTManager
class gitlab.base.RESTObjectList(manager: gitlab.base.RESTManager, obj_cls: Type[gitlab.base.RESTObject], _list: gitlab.client.GitlabList)

Bases: object

Generator object representing a list of RESTObject’s.

This generator uses the Gitlab pagination system to fetch new data when required.

Note: you should not instanciate such objects, they are returned by calls to RESTManager.list()

Parameters

  • manager – Manager to attach to the created objects

  • obj_cls – Type of objects to create from the json data

  • _list – A GitlabList object

property current_page

The current page number.

next()
property next_page

The next page number.

If None, the current page is the last.

property per_page

The number of items per page.

property prev_page

The previous page number.

If None, the current page is the first.

property total

The total number of items.

property total_pages

The total number of pages.

class gitlab.base.RequiredOptional(required, optional)

Bases: tuple

optional: Tuple[str, …]

Alias for field number 1

required: Tuple[str, …]

Alias for field number 0

gitlab.cli module

gitlab.cli.cls_to_what(cls: Any) → str
gitlab.cli.die(msg: str, e: Optional[Exception] = None) → None
gitlab.cli.docs() → argparse.ArgumentParser

Provide a statically generated parser for sphinx only, so we don’t need to provide dummy gitlab config for readthedocs.

gitlab.cli.main()
gitlab.cli.register_custom_action(cls_names: Union[str, Tuple[str, …]], mandatory: Tuple[str, …] = (), optional: Tuple[str, …] = ()) → Callable
gitlab.cli.what_to_cls(what: str) → str

gitlab.config module

exception gitlab.config.ConfigError

Bases: Exception

exception gitlab.config.GitlabConfigHelperError

Bases: gitlab.config.ConfigError

exception gitlab.config.GitlabConfigMissingError

Bases: gitlab.config.ConfigError

class gitlab.config.GitlabConfigParser(gitlab_id: Optional[str] = None, config_files: Optional[List[str]] = None)

Bases: object

exception gitlab.config.GitlabDataError

Bases: gitlab.config.ConfigError

exception gitlab.config.GitlabIDError

Bases: gitlab.config.ConfigError

gitlab.const module

gitlab.exceptions module

exception gitlab.exceptions.GitlabActivateError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabAttachFileError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabAuthenticationError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabError

exception gitlab.exceptions.GitlabBlockError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabBuildCancelError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabCancelError

exception gitlab.exceptions.GitlabBuildEraseError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabRetryError

exception gitlab.exceptions.GitlabBuildPlayError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabRetryError

exception gitlab.exceptions.GitlabBuildRetryError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabRetryError

exception gitlab.exceptions.GitlabCancelError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabCherryPickError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabConnectionError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabError

exception gitlab.exceptions.GitlabCreateError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabDeactivateError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabDeleteError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabError(error_message='', response_code=None, response_body=None)

Bases: Exception

exception gitlab.exceptions.GitlabFollowError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabGetError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabHousekeepingError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabHttpError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabError

exception gitlab.exceptions.GitlabImportError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabJobCancelError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabCancelError

exception gitlab.exceptions.GitlabJobEraseError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabRetryError

exception gitlab.exceptions.GitlabJobPlayError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabRetryError

exception gitlab.exceptions.GitlabJobRetryError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabRetryError

exception gitlab.exceptions.GitlabLicenseError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabListError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabMRApprovalError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabMRClosedError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabMRForbiddenError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabMROnBuildSuccessError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabMRRebaseError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabMarkdownError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabOperationError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabError

exception gitlab.exceptions.GitlabOwnershipError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabParsingError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabError

exception gitlab.exceptions.GitlabPipelineCancelError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabCancelError

exception gitlab.exceptions.GitlabPipelinePlayError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabRetryError

exception gitlab.exceptions.GitlabPipelineRetryError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabRetryError

exception gitlab.exceptions.GitlabProjectDeployKeyError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabProtectError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabRenderError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabRepairError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabRetryError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabRevertError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabSearchError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabSetError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabStopError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabSubscribeError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabTimeTrackingError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabTodoError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabTransferProjectError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabUnblockError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabUnfollowError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabUnsubscribeError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabUpdateError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabUploadError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.GitlabVerifyError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabOperationError

exception gitlab.exceptions.RedirectError(error_message='', response_code=None, response_body=None)

Bases: gitlab.exceptions.GitlabError

gitlab.exceptions.on_http_error(error)

Manage GitlabHttpError exceptions.

This decorator function can be used to catch GitlabHttpError exceptions raise specialized exceptions instead.

Parameters

error (Exception) – The exception type to raise – must inherit from GitlabError

gitlab.mixins module

class gitlab.mixins.AccessRequestMixin

Bases: object

approve(access_level: int = 30, **kwargs: Any) → None

Approve an access request.

Parameters

  • access_level (int) – The access level for the user

  • **kwargs – Extra options to send to the server (e.g. sudo)

Raises
manager: gitlab.base.RESTManager
class gitlab.mixins.BadgeRenderMixin

Bases: object

render(link_url: str, image_url: str, **kwargs: Any) → Dict[str, Any]

Preview link_url and image_url after interpolation.

Parameters

  • link_url (str) – URL of the badge link

  • image_url (str) – URL of the badge image

  • **kwargs – Extra options to send to the server (e.g. sudo)

Raises
Returns

The rendering properties

Return type

dict

class gitlab.mixins.CRUDMixin

Bases: gitlab.mixins.GetMixin, gitlab.mixins.ListMixin, gitlab.mixins.CreateMixin, gitlab.mixins.UpdateMixin, gitlab.mixins.DeleteMixin

gitlab: gitlab.client.Gitlab
class gitlab.mixins.CreateMixin

Bases: object

create(data: Optional[Dict[str, Any]] = None, **kwargs: Any) → gitlab.base.RESTObject

Create a new object.

Parameters

  • data (dict) – parameters to send to the server to create the resource

  • **kwargs – Extra options to send to the server (e.g. sudo)

Returns

a new instance of the managed object class built with

the data sent by the server

Return type

RESTObject

Raises
gitlab: gitlab.client.Gitlab
class gitlab.mixins.DeleteMixin

Bases: object

delete(id: Union[str, int], **kwargs: Any) → None

Delete an object on the server.

Parameters

  • id – ID of the object to delete

  • **kwargs – Extra options to send to the server (e.g. sudo)

Raises
gitlab: gitlab.client.Gitlab
class gitlab.mixins.DownloadMixin

Bases: object

download(streamed: bool = False, action: Optional[Callable] = None, chunk_size: int = 1024, **kwargs: Any) → Optional[bytes]

Download the archive of a resource export.

Parameters

  • streamed (bool) – If True the data will be processed by chunks of chunk_size and each chunk is passed to action for reatment

  • action (callable) – Callable responsible of dealing with chunk of data

  • chunk_size (int) – Size of each chunk

  • **kwargs – Extra options to send to the server (e.g. sudo)

Raises
Returns

The blob content if streamed is False, None otherwise

Return type

str

manager: gitlab.base.RESTManager
class gitlab.mixins.GetMixin

Bases: object

get(id: Union[str, int], lazy: bool = False, **kwargs: Any) → gitlab.base.RESTObject

Retrieve a single object.

Parameters

  • id (int or str) – ID of the object to retrieve

  • lazy (bool) – If True, don’t request the server, but create a shallow object giving access to the managers. This is useful if you want to avoid useless calls to the API.

  • **kwargs – Extra options to send to the server (e.g. sudo)

Returns

The generated RESTObject.

Return type

object

Raises
gitlab: gitlab.client.Gitlab
class gitlab.mixins.GetWithoutIdMixin

Bases: object

get(id: Optional[Union[int, str]] = None, **kwargs: Any) → Optional[gitlab.base.RESTObject]

Retrieve a single object.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Returns

The generated RESTObject

Return type

object

Raises
gitlab: gitlab.client.Gitlab
class gitlab.mixins.ListMixin

Bases: object

gitlab: gitlab.client.Gitlab
list(**kwargs: Any) → Union[gitlab.base.RESTObjectList, List[gitlab.base.RESTObject]]

Retrieve a list of objects.

Parameters

  • all (bool) – If True, return all the items, without pagination

  • per_page (int) – Number of items to retrieve per request

  • page (int) – ID of the page to return (starts with page 1)

  • as_list (bool) – If set to False and no pagination option is defined, return a generator instead of a list

  • **kwargs – Extra options to send to the server (e.g. sudo)

Returns

The list of objects, or a generator if as_list is False

Return type

list

Raises
class gitlab.mixins.NoUpdateMixin

Bases: gitlab.mixins.GetMixin, gitlab.mixins.ListMixin, gitlab.mixins.CreateMixin, gitlab.mixins.DeleteMixin

gitlab: gitlab.client.Gitlab
class gitlab.mixins.ObjectDeleteMixin

Bases: object

Mixin for RESTObject’s that can be deleted.

delete(**kwargs: Any) → None

Delete the object from the server.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises
manager: gitlab.base.RESTManager
class gitlab.mixins.ParticipantsMixin

Bases: object

manager: gitlab.base.RESTManager
participants(**kwargs: Any) → Dict[str, Any]

List the participants.

Parameters

  • all (bool) – If True, return all the items, without pagination

  • per_page (int) – Number of items to retrieve per request

  • page (int) – ID of the page to return (starts with page 1)

  • as_list (bool) – If set to False and no pagination option is defined, return a generator instead of a list

  • **kwargs – Extra options to send to the server (e.g. sudo)

Raises
Returns

The list of participants

Return type

RESTObjectList

class gitlab.mixins.RefreshMixin

Bases: object

manager: gitlab.base.RESTManager
refresh(**kwargs: Any) → None

Refresh a single object from server.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Returns None (updates the object)

Raises
class gitlab.mixins.RetrieveMixin

Bases: gitlab.mixins.ListMixin, gitlab.mixins.GetMixin

gitlab: gitlab.client.Gitlab
class gitlab.mixins.SaveMixin

Bases: object

Mixin for RESTObject’s that can be updated.

manager: gitlab.base.RESTManager
save(**kwargs: Any) → None

Save the changes made to the object to the server.

The object is updated to match what the server returns.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises
class gitlab.mixins.SetMixin

Bases: object

gitlab: gitlab.client.Gitlab
set(key: str, value: str, **kwargs: Any) → gitlab.base.RESTObject

Create or update the object.

Parameters

  • key (str) – The key of the object to create/update

  • value (str) – The value to set for the object

  • **kwargs – Extra options to send to the server (e.g. sudo)

Raises
Returns

The created/updated attribute

Return type

obj

class gitlab.mixins.SubscribableMixin

Bases: object

manager: gitlab.base.RESTManager
subscribe(**kwargs: Any) → None

Subscribe to the object notifications.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises
unsubscribe(**kwargs: Any) → None

Unsubscribe from the object notifications.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises
class gitlab.mixins.TimeTrackingMixin

Bases: object

add_spent_time(duration: str, **kwargs: Any) → Dict[str, Any]

Add time spent working on the object.

Parameters

  • duration (str) – Duration in human format (e.g. 3h30)

  • **kwargs – Extra options to send to the server (e.g. sudo)

Raises
manager: gitlab.base.RESTManager
reset_spent_time(**kwargs: Any) → Dict[str, Any]

Resets the time spent working on the object.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises
reset_time_estimate(**kwargs: Any) → Dict[str, Any]

Resets estimated time for the object to 0 seconds.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises
time_estimate(duration: str, **kwargs: Any) → Dict[str, Any]

Set an estimated time of work for the object.

Parameters

  • duration (str) – Duration in human format (e.g. 3h30)

  • **kwargs – Extra options to send to the server (e.g. sudo)

Raises
time_stats(**kwargs: Any) → Dict[str, Any]

Get time stats for the object.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises
class gitlab.mixins.TodoMixin

Bases: object

manager: gitlab.base.RESTManager
todo(**kwargs: Any) → None

Create a todo associated to the object.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises
class gitlab.mixins.UpdateMixin

Bases: object

gitlab: gitlab.client.Gitlab
update(id: Optional[Union[int, str]] = None, new_data: Optional[Dict[str, Any]] = None, **kwargs: Any) → Dict[str, Any]

Update an object on the server.

Parameters

  • id – ID of the object to update (can be None if not required)

  • new_data – the update data for the object

  • **kwargs – Extra options to send to the server (e.g. sudo)

Returns

The new object data (not a RESTObject)

Return type

dict

Raises
class gitlab.mixins.UserAgentDetailMixin

Bases: object

manager: gitlab.base.RESTManager
user_agent_detail(**kwargs: Any) → Dict[str, Any]

Get the user agent detail.

Parameters

**kwargs – Extra options to send to the server (e.g. sudo)

Raises

gitlab.utils module

gitlab.utils.clean_str_id(id: str) → str
gitlab.utils.copy_dict(dest: Dict[str, Any], src: Dict[str, Any]) → None
gitlab.utils.remove_none_from_dict(data: Dict[str, Any]) → Dict[str, Any]
gitlab.utils.response_content(response: requests.models.Response, streamed: bool, action: Optional[Callable], chunk_size: int) → Optional[bytes]
gitlab.utils.sanitized_url(url: str) → str

Module contents

Wrapper for the GitLab API.