gidgetlab.abc — Abstract base class for simplified requests

While gidgetlab.sansio provides all of the building blocks necessary to make a request to the GitLab API, it still requires you to pull together all the requisite parts of a request for the HTTP library you prefer to use. As that can be repetitive and mostly boilerplate between HTTP libraries, this module was created to abstract out the HTTP library being used so all boilerplate could be taken care.

Users should instantiate an appropriate subclass once for any single set of calls to the GitLab API. By default, the official https://gitlab.com service is used. It’s easy to use a private GitLab instance by passing the url parameter or using the GL_URL environment variable:

gl = GitLabAPI(requester, url="https://mygitlab.example.com")

Or:

export GL_URL=https://mygitlab.example.com

Note that the url parameter takes precedence over the GL_URL environment variable.

Then one can use the appropriate method to make requests simply, e.g.:

# Assume `gl` has an implementation of GitLabAPI.
data = await gl.getitem("/templates/licenses/MIT")

This allows one to use the GitLab API directly without dealing with lower-level details. Most importantly, any changes to the GitLab API does not require an update to the library, allowing one to use experimental APIs without issue.

class gidgetlab.abc.GitLabAPI(requester, *, access_token=None, url=None, api_version='v4', cache=None)

Provide an abstract base class which abstracts out the HTTP library being used to send requests to GitLab. The class is initialized with the requester’s name and optionally their Access token and a cache object.

For methods that send data to GitLab, there is a data argument which accepts an object which can be serialized to JSON (because None is a legitimate JSON value, "" is used to represent no data).

The returned value for GitLab requests is the decoded body of the response according to gidgetlab.sansio.decipher_response(). If the status code returned by the HTTP request is anything other than 200, 201, 202 or 204, then an appropriate HTTPException is raised.

requester

The requester’s name (typically a GitLab username or group name).

access_token

The provided access token (if any). Can be a personal/group/project access token or an Oauth 2.0 token.

api_url

The GitLab API url constructed with the url and api_version optional parameters. Default to https://gitlab.com/api/v4. Can be set to a private GitLab instance by setting the url parameter.

graphql_endpoint

The GitLab GraphQL endpoint constructed with the url and /api/graphql string. Default to https://gitlab.com/api/graphql. Can be set to a private GitLab instance by setting the url parameter.

rate_limit

An instance of gidgetlab.sansio.RateLimit representing the last known rate limit imposed upon the user. This attribute is automatically updated after every successful HTTP request.

abstract async sleep(seconds)

An abstract coroutine which causes the coroutine to sleep for the specified number of seconds. This is provided to help prevent from going over one’s rate limit.

Return type:

None

format_url(url, params)

Construct a URL for the GitLab API.

The URL may be absolute or relative. In the latter case the appropriate domain will be added. This is to help when copying the relative URL directly from the GitLab developer documentation.

The dict provided in params is passed as query string.

Return type:

str

async getitem(url, params={})

Get a single item from GitLab. :rtype: Any

Note

For GET calls that can return multiple values and potentially require pagination, see getiter().

async getiter(url, params={})

Get all items from a GitLab API endpoint.

An asynchronous iterable is returned which will yield all items from the endpoint (i.e. use async for on the result). Any pagination will automatically be followed. :rtype: AsyncGenerator[Any, None]

Note

For GET calls that return only a single item, see getitem().

async post(url, params={}, *, data)

Send a POST request to GitLab.

Return type:

Any

async patch(url, params={}, *, data)

Send a PATCH request to GitLab.

Return type:

Any

async put(url, params={}, *, data=b'')

Send a PUT request to GitLab.

Return type:

Any

async delete(url, params={}, *, data=b'')

Send a DELETE request to GitLab.

Return type:

None

async graphql(query, **variables)

Query the GraphQL API.

The variables kwargs-style argument collects all variables for the query.

Return type:

Any