simple-github

A simple Python Github client that handles auth and provides easy access to the REST and GraphQL APIs.

Why use simple-github?

You might consider simple-github if..

1. You don't want to write your own auth (especially app auth) but also don't want to be stuck with an object oriented wrapper.
2. You want to use both the REST and GraphQL endpoints.

Features

• Authenticate with a personal access token, as a Github App or a Github App installation.
• Automatic refreshing of app tokens on expiry.
• Query both the REST and GraphQL endpoints.
• Shared aiohttp session across both endpoints.

Installation

Install with pip:

pip install simple-github

Example Usage

Authenticate with an access token

In the simplest case, you can provide an access token to use:

from simple_github import TokenClient
token = "<access token>"
async with TokenClient(token) as session:
    resp = await session.get("/octocat")
    resp.raise_for_status()
    data = await resp.json()
    await resp.close()

The return value is an aiohttp.ClientResponse object.

If calling synchronously, simply remove the async / await from the examples:

from simple_github import TokenClient
token = "<access token>"
with TokenClient(token) as session:
    resp = session.get("/octocat")
    resp.raise_for_status()
    data = resp.json()

In this case the return value is a requests.Response object.

Authenticate as a Github App installation

To authenticate as an app installation you'll need:

1. The Github app id for your app.
2. A private key associated with your app. This can be generated from your app's settings page.
3. The organization or user where the app is installed.
4. Optionally a list of repositories to limit access to.

from simple_github import AppClient
app_id = 123
privkey = "<private key>"
owner = "mozilla-releng"

async with AppClient(app_id, privkey, owner=owner) as session:
    resp = await session.get("/octocat")

You can also specify repositories if you want to restrict access.

async with AppClient(app_id, privkey, owner=owner, repositories=["simple-github"]) as session:
    resp = await session.get("/octocat")

The AppClient can be used in both sync and async contexts. If a running async loop is found, an object with awaitable method will be returned, otherwise a normal synchronous object with the same methods will be provided.

Authenticate as a Github App

You can also authenticate as the app itself. This is mainly only useful for administering the app. To do this, simply omit the owner argument.

async with AppClient(app_id, privkey) as session:
    resp = await session.get("/octocat")

Obtain an app token for use with git

Under the hood, the AppClient uses the AppAuth and AppInstallationAuth objects to obtain a GitHub token. It can also be used to pull or push from a repository.

The token can be obtained as follows for a given installation of the app.

app_auth = AppAuth(app_id, privkey)
inst_auth = AppInstallationAuth(app_auth, owner, repositories=["simple-github"])
return await inst_auth.get_token()

The get_token method doesn't natively support synchronous calls, but it can easily be called from synchronous code with

return asyncio.run(inst_auth.get_token())

For convenience, the AppClient provides a get_token() methods hiding those details.

token = await AppClient(app_id, privkey, owner=owner, repositories=["simple-github"]).get_token()

The returned token (ghs_XXX) can be used directly to authenticate git+http operations as the git user.

git remote set-url origin https://git:ghs_XXX@github.com/mozilla-releng/simple-github

No Authentication

Finally you can create a client without any authentication. This is mainly provided for cases where supplying an authentication method is optional, e.g to increase rate limits. This allows for simpler implementations.

from simple_github import PublicClient

async with PublicClient() as session:
    resp = await session.get("/octocat")

Query the REST API

simple-github provides only a very basic wrapper around Github's REST API. You can query it by passing in the path fragment to session.get or session.post.

For example, you can list pull requests with a GET request:

resp = await session.get("/repos/mozilla-releng/simple-github/pulls")
pulls = await resp.json()
await resp.close()
open_pulls = [p for p in pulls if p["state"] == "open"]

Or you can create a pull request with a POST request:

data = {
    "title": "Add feature X",
    "body": "This adds new feature X",
    "head": "simple-github:featureX",
    "base": "main",
}
await session.post("/repos/mozilla-releng/simple-github/pulls", data=data)

Query the GraphQL API

simple-github also supports the GraphQL API. In this example we get the contents of a file:

query = """
  query getFileContents {
    repository(owner: "mozilla-releng", name: "simple-github") {
      object(expression: "HEAD:README.md") {
        ... on Blob {
          text
        }
      }
    }
  }
"""
contents = await session.execute(query)

You can use GraphQL variables via the variables argument to session.execute.