API reference (gitlab package) - python-gitlab v8.2.0

Module contents¶

Wrapper for the GitLab API.

class gitlab.AsyncGraphQL(url: str | None = None, *, token: str | None = None, ssl_verify: bool | str = True, client: AsyncClient | None = None, timeout: float | None = None, user_agent: str = 'python-gitlab/8.2.0', fetch_schema_from_transport: bool = False, max_retries: int = 10, obey_rate_limit: bool = True, retry_transient_errors: bool = False)

Bases: _BaseGraphQL

Parameters:

url (str | None)
token (str | None)
ssl_verify (bool | str)
client (httpx.AsyncClient | None)
timeout (float | None)
user_agent (str)
fetch_schema_from_transport (bool)
max_retries (int)
obey_rate_limit (bool)
retry_transient_errors (bool)

async execute(request: str, *args: Any, **kwargs: Any) → Any

Parameters:

request (str)
args (Any)
kwargs (Any)

Return type:

Any

class gitlab.Gitlab(url: str | None = None, private_token: str | None = None, oauth_token: str | None = None, job_token: str | None = None, ssl_verify: bool | str = True, http_username: str | None = None, http_password: str | None = None, timeout: float | None = None, api_version: str = '4', per_page: int | None = None, pagination: str | None = None, order_by: str | None = None, user_agent: str = 'python-gitlab/8.2.0', retry_transient_errors: bool = False, keep_base_url: bool = False, **kwargs: Any)

Bases: object

Represents a GitLab server connection.

Parameters:

url (str | None) – The URL of the GitLab server (defaults to https://gitlab.com).
private_token (str | None) – The user private token
oauth_token (str | None) – An oauth token
job_token (str | None) – A CI job token
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 | None) – Timeout to use for requests to the GitLab server.
http_username (str | None) – Username for HTTP authentication
http_password (str | None) – Password for HTTP authentication
api_version (str) – Gitlab API version to use (support for 4 only)
pagination (str | None) – Can be set to ‘keyset’ to use keyset pagination
order_by (str | None) – Set order_by globally
user_agent (str) – A custom user agent to use for making HTTP requests.
retry_transient_errors (bool) – Whether to retry after 500, 502, 503, 504 or 52x responses. Defaults to False.
keep_base_url (bool) – keep user-provided base URL for pagination if it differs from response headers
session (requests.Session) – HTTP Requests Session
backend (RequestsBackend) – Backend that will be used to make http requests
per_page (int | None)
kwargs (Any)

property api_url: str: The computed API base URL.

property api_version: str: The API version used (4 only).

appearance: See ApplicationAppearanceManager

applications: See ApplicationManager

audit_events: See AuditEventManager

auth() → None

Performs an authentication using private token. Warns the user if a potentially misconfigured URL is detected on the client or server side.

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

Return type:: None

broadcastmessages: See BroadcastMessageManager

bulk_import_entities: See BulkImportAllEntityManager

bulk_imports: See BulkImportManager

ci_lint: See CiLintManager

deploykeys: See DeployKeyManager

deploytokens: See DeployTokenManager

dockerfiles: See DockerfileManager

enable_debug(mask_credentials: bool = True) → None

Parameters:: mask_credentials (bool)
Return type:: None

events: See EventManager

features: See FeatureManager

classmethod from_config(gitlab_id: str | None = None, config_files: list[str] | None = None, **kwargs: Any) → Gitlab

Create a Gitlab connection from configuration files.

Parameters:

gitlab_id (str | None) – ID of the configuration section.
list[str] (config_files) – List of paths to configuration files.
config_files (list[str] | None)
kwargs (Any)

Return type:

Gitlab

kwargs:: session requests.Session: Custom requests Session

Returns:

A Gitlab connection.

Raises:

gitlab.config.GitlabDataError – If the configuration is not correct.

Parameters:

gitlab_id (str | None)
config_files (list[str] | None)
kwargs (Any)

Return type:

Gitlab

geonodes: See GeoNodeManager

get_license(**kwargs: Any) → dict[str, str | dict[str, str]]

Retrieve information about the current license.

Parameters:

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

Raises:

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

Returns:

The current license information

Return type:

dict[str, str | dict[str, str]]

gitignores: See GitignoreManager

gitlabciymls: See GitlabciymlManager

groups: See GroupManager

headers: Headers that will be used in request to GitLab

hooks: See HookManager

http_delete(path: str, **kwargs: Any) → Response

Make a DELETE request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Returns:

The requests object.

Raises:

GitlabHttpError – When the return code is not 2xx

Return type:

Response

http_get(path: str, query_data: dict[str, Any] | None = None, streamed: bool = False, raw: bool = False, **kwargs: Any) → dict[str, Any] | Response

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[str, Any] | None) – Data to send as query parameters
streamed (bool) – Whether the data should be streamed
raw (bool) – If True do not try to parse the output as json
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

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

Return type:

dict[str, Any] | Response

http_head(path: str, query_data: dict[str, Any] | None = None, **kwargs: Any) → CaseInsensitiveDict[Any]

Make a HEAD request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
query_data (dict[str, Any] | None) – Data to send as query parameters
**kwargs (Any) – Extra options to send to the server (e.g. sudo, page, per_page)

Returns:

A requests.header object

Raises:

GitlabHttpError – When the return code is not 2xx

Return type:

CaseInsensitiveDict[Any]

http_list(path: str, query_data: dict[str, Any] | None = None, *, iterator: bool | None = None, message_details: WarnMessageData | None = None, **kwargs: Any) → GitlabList | list[dict[str, Any]]

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/projects’)
query_data (dict[str, Any] | None) – Data to send as query parameters
iterator (bool | None) – Indicate if should return a generator (True)
**kwargs (Any) – Extra options to send to the server (e.g. sudo, page, per_page)
message_details (WarnMessageData | None)
**kwargs

Returns:

A list of the objects returned by the server. If iterator is True and no pagination-related arguments (page, per_page, get_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.

Raises:

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

Return type:

GitlabList | list[dict[str, Any]]

http_patch(path: str, *, query_data: dict[str, Any] | None = None, post_data: dict[str, Any] | bytes | None = None, raw: bool = False, **kwargs: Any) → dict[str, Any] | Response

Make a PATCH request to the Gitlab server.

Parameters:

path (str) – Path or full URL to query (‘/projects’ or ‘http://whatever/v4/api/projecs’)
query_data (dict[str, Any] | None) – Data to send as query parameters
post_data (dict[str, Any] | bytes | None) – Data to send in the body (will be converted to json by default)
raw (bool) – If True, do not convert post_data to json
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

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

Return type:

dict[str, Any] | Response

http_post(path: str, query_data: dict[str, Any] | None = None, post_data: dict[str, Any] | None = None, raw: bool = False, files: dict[str, Any] | None = None, **kwargs: Any) → dict[str, Any] | Response

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[str, Any] | None) – Data to send as query parameters
post_data (dict[str, Any] | None) – Data to send in the body (will be converted to json by default)
raw (bool) – If True, do not convert post_data to json
files (dict[str, Any] | None) – The files to send to the server
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

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

Return type:

dict[str, Any] | Response

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[str, Any] | None) – Data to send as query parameters
post_data (dict[str, Any] | bytes | BinaryIO | None) – Data to send in the body (will be converted to json by default)
raw (bool) – If True, do not convert post_data to json
files (dict[str, Any] | None) – The files to send to the server
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

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

Return type:

dict[str, Any] | Response

http_request(verb: str, path: str, query_data: dict[str, Any] | None = None, post_data: dict[str, Any] | bytes | BinaryIO | None = None, raw: bool = False, streamed: bool = False, files: dict[str, Any] | None = None, timeout: float | None = None, obey_rate_limit: bool = True, retry_transient_errors: bool | None = None, max_retries: int = 10, extra_headers: dict[str, Any] | None = None, **kwargs: Any) → Response

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[str, Any] | None) – Data to send as query parameters
post_data (dict[str, Any] | bytes | BinaryIO | None) – Data to send in the body (will be converted to json by default)
raw (bool) – If True, do not convert post_data to json
streamed (bool) – Whether the data should be streamed
files (dict[str, Any] | None) – The files to send to the server
timeout (float | None) – The timeout, in seconds, for the request
obey_rate_limit (bool) – Whether to obey 429 Too Many Request responses. Defaults to True.
retry_transient_errors (bool | None) – Whether to retry after 500, 502, 503, 504 or 52x responses. Defaults to False.
max_retries (int) – Max retries after 429 or transient errors, set to -1 to retry forever. Defaults to 10.
extra_headers (dict[str, Any] | None) – Add and override HTTP headers for the request.
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Returns:

A requests result object.

Raises:

GitlabHttpError – When the return code is not 2xx

Return type:

Response

issues: See IssueManager

issues_statistics: See IssuesStatisticsManager

keys: See KeyManager

ldapgroups: See LDAPGroupManager

licenses: See LicenseManager

markdown(text: str, gfm: bool = False, project: str | None = None, **kwargs: Any) → str

Render an arbitrary Markdown document.

Parameters:

text (str) – The markdown text to render
gfm (bool) – Render text using GitLab Flavored Markdown. Default is False
project (str | None) – Full path of a project used a context when gfm is True
**kwargs (Any) – Extra options to send to the server (e.g. sudo)

Raises:

GitlabAuthenticationError – If authentication is not correct
GitlabMarkdownError – If the server cannot perform the request

Returns:

The HTML rendering of the markdown text.

Return type:

str

member_roles: See MergeRequestManager

classmethod merge_config(options: dict[str, Any], gitlab_id: str | None = None, config_files: list[str] | None = None) → Gitlab

Create a Gitlab connection by merging configuration with the following precedence:

Explicitly provided CLI arguments,
Environment variables,
Configuration files:
1. explicitly defined config files:
  
  via the –config-file CLI argument,
  
  via the PYTHON_GITLAB_CFG environment variable,
2. user-specific config file,
3. system-level config file,
Environment variables always present in CI (CI_SERVER_URL, CI_JOB_TOKEN).

Parameters:

options (dict[str, Any]) – A dictionary of explicitly provided key-value options.
gitlab_id (str | None) – ID of the configuration section.
config_files (list[str] | None) – List of paths to configuration files.

Returns: