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 than200
,201
,202
or204
, then an appropriateHTTPException
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:
- 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:
- 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, seegetiter()
.
- 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, seegetitem()
.