gidgetlab — An async library for calling GitLab’s API

https://img.shields.io/badge/code%20style-black-000000.svg pre-commit Documentation Status https://gitlab.com/beenje/gidgetlab/badges/master/pipeline.svg https://gitlab.com/beenje/gidgetlab/badges/master/coverage.svg

This library is based on gidgethub from Brett Cannon, an async GitHub API library.

I liked the concept with the asynchronous and sans-I/O approach and decided to adapt it to the GitLab’s API. All credit to Brett Cannon for the initial library!

The main goal is to easily write GitLab bots: applications that run automation on GitLab, using GitLab WebHooks and API. This was inspired by Mariatta PyCon 2018 workshop: Build-a-GitHub-Bot Workshop.

This project has three primary layers to it. The base layer is gidgetlab.sansio and gidgetlab.routing which provide the tools necessary to work with GitLab’s API. The next layer up is gidgetlab.abc which provides an abstract base class for a cleaner, unified API. Finally, the top layer is using an implementation of the abstract base class, e.g. gidgetlab.aiohttp.

The gidgetlab.aiohttp module even provides a GitLabBot class to easily create an aiohttp web server that responds to GitLab webhooks.

Quick start

Here is a complete example of a server that responds to webhooks which will greet the author and say thanks whenever an issue is opened:

from gidgetlab.aiohttp import GitLabBot

bot = GitLabBot("beenje")


@bot.router.register("Issue Hook", action="open")
async def issue_opened_event(event, gl, *args, **kwargs):
    """Whenever an issue is opened, greet the author and say thanks."""
    url = f"/projects/{event.project_id}/issues/{event.object_attributes['iid']}/notes"
    message = f"Thanks for the report @{event.data['user']['username']}! I will look into it ASAP! (I'm a bot)."
    await gl.post(url, data={"body": message})


if __name__ == "__main__":
    bot.run()

Installation

This package requires Python 3.8 or above.

Gidgetlab is on PyPI.

python3 -m pip install gidgetlab

To install web server support (e.g. for aiohttp, httpx, treq, or tornado), specify it as an extra dependency:

python3 -m pip install gidgetlab[aiohttp]

You can get the source from GitLab: https://gitlab.com/beenje/gidgetlab

git clone https://gitlab.com/beenje/gidgetlab.git

Please use the navigation sidebar on the left to begin.