# gitlab package

## Subpackages

- gitlab.v3 package
  - Submodules
  - gitlab.v3.objects module
  - Module contents
- gitlab.v4 package
  - Submodules
  - gitlab.v4.objects module
  - Module contents

## Submodules

## gitlab.base module

class `gitlab.base.``BaseManager`(gl, parent=None, args=[])

  Bases: `object`

  Base manager class for API operations.

  Managers provide method to manage GitLab API objects, such as retrieval, listing, creation.

  Inherited class must define the `obj_cls` attribute.

  `obj_cls`

    class – class of objects wrapped by this manager.

  `create`(data, **kwargs)

    Create a new object of class obj_cls.

    Parameters:

    - data (dict) – The parameters to send to the GitLab server to create the object. Required and optional arguments are defined in the requiredCreateAttrs and optionalCreateAttrs of the obj_cls class.
    - **kwargs – Additional arguments to send to GitLab.

    Returns: | A newly create obj_cls object.
    Return type: | object

    Raises:

    - `NotImplementedError` – If objects cannot be created.
    - `GitlabCreateError` – If the server fails to perform the request.

  `delete`(id, **kwargs)

    Delete a GitLab object.

    Parameters: | id – ID of the object to delete.

    Raises:

    - `NotImplementedError` – If objects cannot be deleted.
    - `GitlabDeleteError` – If the server fails to perform the request.

  `get`(id=None, **kwargs)

    Get a GitLab object.

    Parameters:

    - id – ID of the object to retrieve.
    - **kwargs – Additional arguments to send to GitLab.

    Returns: | An object of class obj_cls.
    Return type: | object

    Raises:

    - `NotImplementedError` – If objects cannot be retrieved.
    - `GitlabGetError` – If the server fails to perform the request.

  `list`(**kwargs)

    Get a list of GitLab objects.

    Parameters: | **kwargs – Additional arguments to send to GitLab.
    Returns: | A list of obj_cls objects.
    Return type: | list[object]

    Raises:

    - `NotImplementedError` – If objects cannot be listed.
    - `GitlabListError` – If the server fails to perform the request.

  `obj_cls` = None

class `gitlab.base.``GitlabObject`(gl, data=None, **kwargs)

  Bases: `object`

  Base class for all classes that interface with GitLab.

  `save`(**kwargs)

    Send the modified object to the GitLab server. The following attributes are sent:

    Available keys for `kwargs` are:

    - `sudo` (string or int): run the request as another user (requires admin permissions)
  `as_dict`()

    Dump the object as a dict.

  `canCreate` = True

    Tells if GitLab-api allows creation of new objects.

  `canDelete` = True

    Tells if GitLab-api allows deleting object.

  `canGet` = True

    Tells if GitLab-api allows retrieving single objects.

  `canList` = True

    Tells if GitLab-api allows listing of objects.

  `canUpdate` = True

    Tells if GitLab-api allows updating object.

  classmethod `create`(gl, data, **kwargs)

    Create an object.

    Parameters:

    - gl (gitlab.Gitlab) – Gitlab object referencing the GitLab server.
    - data (dict) – The data used to define the object.

    Returns: | The new object.
    Return type: | object

    Raises:

    - `NotImplementedError` – If objects can’t be created.
    - `GitlabCreateError` – If the server cannot perform the request.

  `delete`(**kwargs)
  `display`(pretty)
  classmethod `get`(gl, id, **kwargs)

    Retrieve a single object.

    Parameters:

    - gl (gitlab.Gitlab) – Gitlab object referencing the GitLab server.
    - id (int or str) – ID of the object to retrieve.

    Returns: | The found GitLab object.
    Return type: | object

    Raises:

    - `NotImplementedError` – If objects can’t be retrieved.
    - `GitlabGetError` – If the server cannot perform the request.

  `getRequiresId` = True

    Whether the object ID is required in the GET url.

  `gitlab` = None

    (gitlab.Gitlab) – Gitlab connection.

  `idAttr` = 'id'

    Name of the identifier of an object.

  `json`()

    Dump the object as json.

    Returns: | The json string.
    Return type: | str

  classmethod `list`(gl, **kwargs)

    Retrieve a list of objects from GitLab.

    Parameters:

    - gl (gitlab.Gitlab) – Gitlab object referencing the GitLab server.
    - per_page (int) – Maximum number of items to return.
    - page (int) – ID of the page to return when using pagination.

    Returns: | A list of objects.
    Return type: | list[object]

    Raises:

    - `NotImplementedError` – If objects can’t be listed.
    - `GitlabListError` – If the server cannot perform the request.

  `managers` = []

    List of managers to create.

  `optionalCreateAttrs` = []

    Attributes that are optional when creating a new object.

  `optionalGetAttrs` = []

    Attributes that are optional when retrieving single object.

  `optionalListAttrs` = []

    Attributes that are optional when retrieving list of objects.

  `optionalUpdateAttrs` = []

    Attributes that are optional when updating an object.

  `pretty_print`(depth=0)

    Print the object on the standard output (verbose).

    Parameters: | depth (int) – Used internaly for recursive call.

  `requiredCreateAttrs` = []

    Attributes that are required when creating a new object.

  `requiredDeleteAttrs` = []

    Attributes that are required when deleting object.

  `requiredGetAttrs` = []

    Attributes that are required when retrieving single object.

  `requiredListAttrs` = []

    Attributes that are required when retrieving list of objects.

  `requiredUpdateAttrs` = []

    Attributes that are required when updating an object.

  `requiredUrlAttrs` = []

    Attributes that are required for constructing url.

  `save`(**kwargs)
  `shortPrintAttr` = None

    Attribute to use as ID when displaying the object.

  `short_print`(depth=0)

    Print the object on the standard output (verbose).

    Parameters: | depth (int) – Used internaly for recursive call.

class `gitlab.base.``RESTManager`(gl, parent=None)

  Bases: `object`

  Base class for CRUD operations on objects.

  Derivated 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

  `parent_attrs`
  `path`

class `gitlab.base.``RESTObject`(manager, attrs)

  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.

  `attributes`
  `get_id`()

    Returns the id of the resource.

class `gitlab.base.``RESTObjectList`(manager, obj_cls, _list)

  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

  `current_page`

    The current page number.

  `next`()
  `next_page`

    The next page number.

    If None, the current page is the last.

  `per_page`

    The number of items per page.

  `prev_page`

    The next page number.

    If None, the current page is the last.

  `total`

    The total number of items.

  `total_pages`

    The total number of pages.

class `gitlab.base.``jsonEncoder`(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None)

  Bases: `json.encoder.JSONEncoder`

  `default`(obj)

## gitlab.cli module

`gitlab.cli.``cls_to_what`(cls)

`gitlab.cli.``die`(msg, e=None)

`gitlab.cli.``main`()

`gitlab.cli.``register_custom_action`(cls_names, mandatory=(), optional=())

`gitlab.cli.``what_to_cls`(what)

## gitlab.config module

exception `gitlab.config.``ConfigError`

  Bases: `exceptions.Exception`

class `gitlab.config.``GitlabConfigParser`(gitlab_id=None, config_files=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.``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.``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: `exceptions.Exception`

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.``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.``GitlabListError`(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.``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.``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.``GitlabRetryError`(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.``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.``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`

`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.exceptions.``raise_error_from_response`(response, error, expected_code=200)

  Tries to parse gitlab error message from response and raises error.

  Do nothing if the response status is the expected one.

  If response status code is 401, raises instead GitlabAuthenticationError.

  Parameters:

  - response – requests response object
  - error – Error-class or dict {return-code => class} of possible error class to raise. Should be inherited from GitLabError

## gitlab.mixins module

class `gitlab.mixins.``AccessRequestMixin`

  Bases: `object`

  `approve`(*args, **kwargs)

    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:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabUpdateError` – If the server fails to perform the request

class `gitlab.mixins.``CRUDMixin`

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

class `gitlab.mixins.``CreateMixin`

  Bases: `object`

  `create`(*args, **kwargs)

    Create a new object.

    Parameters:

    - data (dict) – parameters to send to the server to create the resource
    - **kwargs – Extra options to send to the Gitlab 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:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabCreateError` – If the server cannot perform the request

  `get_create_attrs`()

    Return the required and optional arguments.

    Returns:

    2 items: list of required arguments and list of optional
      arguments for creation (in that order)

    Return type: | tuple

class `gitlab.mixins.``DeleteMixin`

  Bases: `object`

  `delete`(*args, **kwargs)

    Delete an object on the server.

    Parameters:

    - id – ID of the object to delete
    - **kwargs – Extra options to send to the Gitlab server (e.g. sudo)

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabDeleteError` – If the server cannot perform the request

class `gitlab.mixins.``GetFromListMixin`

  Bases: `gitlab.mixins.ListMixin`

  `get`(id, **kwargs)

    Retrieve a single object.

    Parameters:

    - id (int or str) – ID of the object to retrieve
    - **kwargs – Extra options to send to the Gitlab server (e.g. sudo)

    Returns: | The generated RESTObject
    Return type: | object

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabGetError` – If the server cannot perform the request

class `gitlab.mixins.``GetMixin`

  Bases: `object`

  `get`(*args, **kwargs)

    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 Gitlab server (e.g. sudo)

    Returns: | The generated RESTObject.
    Return type: | object

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabGetError` – If the server cannot perform the request

class `gitlab.mixins.``GetWithoutIdMixin`

  Bases: `object`

  `get`(*args, **kwargs)

    Retrieve a single object.

    Parameters: | **kwargs – Extra options to send to the Gitlab server (e.g. sudo)
    Returns: | The generated RESTObject
    Return type: | object

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabGetError` – If the server cannot perform the request

class `gitlab.mixins.``ListMixin`

  Bases: `object`

  `list`(*args, **kwargs)

    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 Gitlab server (e.g. sudo)

    Returns: | The list of objects, or a generator if as_list is False
    Return type: | list

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabListError` – If the server cannot perform the request

class `gitlab.mixins.``NoUpdateMixin`

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

class `gitlab.mixins.``ObjectDeleteMixin`

  Bases: `object`

  Mixin for RESTObject’s that can be deleted.

  `delete`(**kwargs)

    Delete the object from the server.

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

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabDeleteError` – If the server cannot perform the request

class `gitlab.mixins.``RetrieveMixin`

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

class `gitlab.mixins.``SaveMixin`

  Bases: `object`

  Mixin for RESTObject’s that can be updated.

  `save`(**kwargs)

    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)

    Raise:
      GitlabAuthenticationError: If authentication is not correct GitlabUpdateError: If the server cannot perform the request

class `gitlab.mixins.``SetMixin`

  Bases: `object`

  `set`(*args, **kwargs)

    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:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabSetError` – If an error occured

    Returns: | The created/updated attribute
    Return type: | obj

class `gitlab.mixins.``SubscribableMixin`

  Bases: `object`

  `subscribe`(*args, **kwargs)

    Subscribe to the object notifications.

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

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabSubscribeError` – If the subscription cannot be done

  `unsubscribe`(*args, **kwargs)

    Unsubscribe from the object notifications.

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

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabUnsubscribeError` – If the unsubscription cannot be done

class `gitlab.mixins.``TimeTrackingMixin`

  Bases: `object`

  `add_spent_time`(*args, **kwargs)

    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:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabTimeTrackingError` – If the time tracking update cannot be done

  `reset_spent_time`(*args, **kwargs)

    Resets the time spent working on the object.

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

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabTimeTrackingError` – If the time tracking update cannot be done

  `reset_time_estimate`(*args, **kwargs)

    Resets estimated time for the object to 0 seconds.

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

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabTimeTrackingError` – If the time tracking update cannot be done

  `time_estimate`(*args, **kwargs)

    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:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabTimeTrackingError` – If the time tracking update cannot be done

  `time_stats`(*args, **kwargs)

    Get time stats for the object.

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

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabTimeTrackingError` – If the time tracking update cannot be done

class `gitlab.mixins.``TodoMixin`

  Bases: `object`

  `todo`(*args, **kwargs)

    Create a todo associated to the object.

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

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabTodoError` – If the todo cannot be set

class `gitlab.mixins.``UpdateMixin`

  Bases: `object`

  `get_update_attrs`()

    Return the required and optional arguments.

    Returns:

    2 items: list of required arguments and list of optional
      arguments for update (in that order)

    Return type: | tuple

  `update`(*args, **kwargs)

    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 Gitlab server (e.g. sudo)

    Returns: | The new object data (not a RESTObject)
    Return type: | dict

    Raises:

    - `GitlabAuthenticationError` – If authentication is not correct
    - `GitlabUpdateError` – If the server cannot perform the request

## gitlab.utils module

`gitlab.utils.``response_content`(response, streamed, action, chunk_size)

## Module contents

Wrapper for the GitLab API.

class `gitlab.``Gitlab`(url, private_token=None, oauth_token=None, email=None, password=None, ssl_verify=True, http_username=None, http_password=None, timeout=None, api_version='4', session=None)

  Bases: `object`

  Represents a GitLab server connection.

  Parameters:

  - url (str) – The URL of the GitLab server.
  - private_token (str) – The user private token
  - oauth_token (str) – An oauth token
  - email (str) – The user email or login.
  - password (str) – The user password (associated with email).
  - ssl_verify (bool|str) – Whether SSL certificates should be validated. If the value is a string, it is the path to a CA file used for certificate validation.
  - timeout (float) – Timeout to use for requests to the GitLab server.
  - http_username (str) – Username for HTTP authentication
  - http_password (str) – Password for HTTP authentication
  - api_version (str) – Gitlab API version to use (3 or 4)

  `api_version`
  `auth`()

    Performs an authentication.

    Uses either the private token, or the email/password pair.

    The user attribute will hold a gitlab.objects.CurrentUser object on success.

  `create`(obj, **kwargs)

    Create an object on the GitLab server.

    The object class and attributes define the request to be made on the GitLab server.

    Parameters:

    - obj (object) – The object to create.
    - **kwargs – Additional arguments to send to GitLab.

    Returns:

    A json representation of the object as returned by the GitLab

      server

    Return type: | str

    Raises:

    - `GitlabConnectionError` – If the server cannot be reached.
    - `GitlabCreateError` – If the server fails to perform the request.

  `delete`(obj, id=None, **kwargs)

    Delete an object on the GitLab server.

    Parameters:

    - obj (object or id) – The object, or the class of the object to delete. If it is the class, the id of the object must be specified as the id arguments.
    - id – ID of the object to remove. Required if obj is a class.
    - **kwargs – Additional arguments to send to GitLab.

    Returns: | True if the operation succeeds.
    Return type: | bool

    Raises:

    - `GitlabConnectionError` – If the server cannot be reached.
    - `GitlabDeleteError` – If the server fails to perform the request.

  `email` = None

    The user email

  `enable_debug`()
  static `from_config`(gitlab_id=None, config_files=None)

    Create a Gitlab connection from configuration files.

    Parameters:

    - gitlab_id (str) – ID of the configuration section.
    - list[str] (config_files) – List of paths to configuration files.

    Returns: | A Gitlab connection.
    Return type: | (gitlab.Gitlab)
    Raises: | `gitlab.config.GitlabDataError` – If the configuration is not correct.

  `get`(obj_class, id=None, **kwargs)

    Request a GitLab resources.

    Parameters:

    - obj_class (object) – The class of resource to request.
    - id – The object ID.
    - **kwargs – Additional arguments to send to GitLab.

    Returns: | An object of class obj_class.
    Return type: | obj_class

    Raises:

    - `GitlabConnectionError` – If the server cannot be reached.
    - `GitlabGetError` – If the server fails to perform the request.

  `headers` = None

    Headers that will be used in request to GitLab

  `http_delete`(path, **kwargs)

    Make a PUT request to the Gitlab server.

    Parameters:

    - path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
    - **kwargs – Extra data to make the query (e.g. sudo, per_page, page)

    Returns: | The requests object.
    Raises: | `GitlabHttpError` – When the return code is not 2xx

  `http_get`(path, query_data={}, streamed=False, **kwargs)

    Make a GET request to the Gitlab server.

    Parameters:

    - path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
    - query_data (dict) – Data to send as query parameters
    - streamed (bool) – Whether the data should be streamed
    - **kwargs – Extra data to make the query (e.g. sudo, per_page, page)

    Returns: | A requests result object is streamed is True or the content type is not json. The parsed json data otherwise.

    Raises:

    - `GitlabHttpError` – When the return code is not 2xx
    - `GitlabParsingError` – If the json data could not be parsed

  `http_list`(path, query_data={}, as_list=None, **kwargs)

    Make a GET request to the Gitlab server for list-oriented queries.

    Parameters:

    - path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
    - query_data (dict) – Data to send as query parameters
    - **kwargs – Extra data to make the query (e.g. sudo, per_page, page, all)

    Returns: | A list of the objects returned by the server. If as_list is False and no pagination-related arguments (page, per_page, all) are defined then a GitlabList object (generator) is returned instead. This object will make API calls when needed to fetch the next items from the server.
    Return type: | list

    Raises:

    - `GitlabHttpError` – When the return code is not 2xx
    - `GitlabParsingError` – If the json data could not be parsed

  `http_post`(path, query_data={}, post_data={}, files=None, **kwargs)

    Make a POST request to the Gitlab server.

    Parameters:

    - path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
    - query_data (dict) – Data to send as query parameters
    - post_data (dict) – Data to send in the body (will be converted to json)
    - **kwargs – Extra data to make the query (e.g. sudo, per_page, page)

    Returns: | The parsed json returned by the server if json is return, else the raw content

    Raises:

    - `GitlabHttpError` – When the return code is not 2xx
    - `GitlabParsingError` – If the json data could not be parsed

  `http_put`(path, query_data={}, post_data={}, **kwargs)

    Make a PUT request to the Gitlab server.

    Parameters:

    - path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
    - query_data (dict) – Data to send as query parameters
    - post_data (dict) – Data to send in the body (will be converted to json)
    - **kwargs – Extra data to make the query (e.g. sudo, per_page, page)

    Returns: | The parsed json returned by the server.

    Raises:

    - `GitlabHttpError` – When the return code is not 2xx
    - `GitlabParsingError` – If the json data could not be parsed

  `http_request`(verb, path, query_data={}, post_data={}, streamed=False, files=None, **kwargs)

    Make an HTTP request to the Gitlab server.

    Parameters:

    - verb (str) – The HTTP method to call (‘get’, ‘post’, ‘put’, ‘delete’)
    - path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
    - query_data (dict) – Data to send as query parameters
    - post_data (dict) – Data to send in the body (will be converted to json)
    - streamed (bool) – Whether the data should be streamed
    - **kwargs – Extra data to make the query (e.g. sudo, per_page, page)

    Returns: | A requests result object.
    Raises: | `GitlabHttpError` – When the return code is not 2xx

  `list`(obj_class, **kwargs)

    Request the listing of GitLab resources.

    Parameters:

    - obj_class (object) – The class of resource to request.
    - **kwargs – Additional arguments to send to GitLab.

    Returns: | A list of objects of class obj_class.
    Return type: | list(obj_class)

    Raises:

    - `GitlabConnectionError` – If the server cannot be reached.
    - `GitlabListError` – If the server fails to perform the request.

  `password` = None

    The user password (associated with email)

  `session` = None

    Create a session object for requests

  `ssl_verify` = None

    Whether SSL certificates should be validated

  `timeout` = None

    Timeout to use for requests to gitlab server

  `update`(obj, **kwargs)

    Update an object on the GitLab server.

    The object class and attributes define the request to be made on the GitLab server.

    Parameters:

    - obj (object) – The object to create.
    - **kwargs – Additional arguments to send to GitLab.

    Returns:

    A json representation of the object as returned by the GitLab

      server

    Return type: | str

    Raises:

    - `GitlabConnectionError` – If the server cannot be reached.
    - `GitlabUpdateError` – If the server fails to perform the request.

  `version`()

    Returns the version and revision of the gitlab server.

    Note that self.version and self.revision will be set on the gitlab object.

    Returns:

    The server version and server revision, or
      (‘unknown’, ‘unknwown’) if the server doesn’t support this API call (gitlab < 8.13.0)

    Return type: | tuple (str, str)

class `gitlab.``GitlabList`(gl, url, query_data, get_next=True, **kwargs)

  Bases: `object`

  Generator representing a list of remote objects.

  The object handles the links returned by a query to the API, and will call the API again when needed.

  `current_page`

    The current page number.

  `next`()
  `next_page`

    The next page number.

    If None, the current page is the last.

  `per_page`

    The number of items per page.

  `prev_page`

    The next page number.

    If None, the current page is the last.

  `total`

    The total number of items.

  `total_pages`

    The total number of pages.