3つの方法の位置づけ

この回で扱う3つは、どれも最終的には GitHub の API を呼んでいる。違うのは、どこまでを道具に任せるかだ。

方法中身任せられることトークン
PyGithubREST API を包んだ Python ライブラリヘッダー、ページネーション、JSON からオブジェクトへの変換公開リポジトリなら省略可
GraphQL APIREST とは別の API。欲しい項目を問い合わせ文で指定する項目の取捨選択。関連する情報をまとめて取得必須
GitHub CLI(gh)GitHub 公式のコマンド。gh api で REST も GraphQL も呼べる認証(トークンの保管)、ページネーション、JSON の整形gh auth login で一度サインインする

PyGithub で取得する

PyGithub は、GitHub の REST API を Python のオブジェクトとして扱えるようにしたライブラリだ。

ターミナル
pip install PyGithub

お題の実装は次のとおり。PART 03 で自分で書いたヘッダーの設定とページネーションが、すべてなくなっている。

Python(commits_pygithub.py)
"""PyGithub でコミット履歴を取得して表示する"""
import os
from datetime import timedelta, timezone

from github import Auth, Github

JST = timezone(timedelta(hours=9))

token = os.environ.get("GITHUB_TOKEN")
gh = Github(auth=Auth.Token(token), per_page=100) if token else Github(per_page=100)

repo = gh.get_repo("VBA-tools/VBA-JSON")
for c in repo.get_commits()[:8]:            # スライスした分だけ取得される
    a = c.commit.author
    when = a.date.astimezone(JST)
    subject = (c.commit.message.splitlines() or [""])[0]
    print(f"{when:%Y-%m-%d %H:%M}  {a.name:<12.12}  {c.sha[:7]}  {subject}")

remaining, limit = gh.rate_limiting         # 直前のレスポンスヘッダーの値
print(f"--- レート制限の残り {remaining}/{limit}")
gh.close()

出力は PART 03 と同じ8行で、最後にレート制限の残りが表示される。

オブジェクトと JSON の対応

PyGithub のオブジェクトの属性は、REST API の JSON の構造とほぼ同じ名前になっている。PART 03 のレスポンスと見比べると対応がわかる。

取りたいものREST API の JSONPyGithub
SHAshac.sha
作者名commit.author.namec.commit.author.name
日時commit.author.date(文字列)c.commit.author.date(タイムゾーン付きの datetime)
メッセージcommit.messagec.commit.message
GitHub のユーザー名author.loginc.author.login(c.author が None のことがある)
変更行数(詳細の API)stats.additionsc.stats.additions・c.stats.deletions

絞り込み

get_commits の引数は、REST API のパラメーターと同じ名前だ。日時は文字列ではなく datetime で渡す。

Python(絞り込みの例)
from datetime import datetime, timezone

commits = repo.get_commits(
    path="JsonConverter.bas",
    since=datetime(2018, 1, 1, tzinfo=JST).astimezone(timezone.utc),   # UTC に直して渡す
    # sha="develop", author="timhall", until=... も指定できる
)
print(commits.totalCount)   # 条件に合う件数

since と until は、UTC に直してから渡す。PyGithub は渡された datetime のタイムゾーンを変換せず、時刻の数字をそのまま UTC として送るため、日本時間のまま渡すと9時間ずれる。

⚠️ 見えないところでリクエストが増える

PyGithub は、必要になった時点で API を呼ぶ(遅延取得)。get_commits() の結果を for で回すと、100件ごとに次のページを自動で取りに行く。また、一覧に含まれない c.stats や c.files に触れると、その場でコミット1件分の詳細を取得する。ループの中で c.stats.additions と書くだけで、コミットの数だけリクエストが増える点は PART 03 と変わらない。回数が気になるときは、gh.rate_limiting で残りを確かめる。

GraphQL API で取得する

GraphQL API は、「どの項目が欲しいか」を問い合わせ文(クエリ)に書いて、1つの URL に POST する API だ。REST API との違いは次の3点である。

  • 欲しい項目だけが返る。REST API のコミット一覧は1件あたり数十項目を返すが、GraphQL は指定した項目しか返さない
  • 関連する情報を1回で取れる。コミットの additions・deletions(追加・削除行数)は一覧の中で指定できるので、コミットごとの追加リクエストが要らない
  • トークンが必須。公開リポジトリでも、トークンなしでは呼べない

クエリ

お題に発展課題(変更ファイル数と行数)を加えたクエリは次のようになる。

GraphQL
query($owner: String!, $name: String!, $cursor: String) {
  repository(owner: $owner, name: $name) {
    defaultBranchRef {
      target {
        ... on Commit {
          history(first: 100, after: $cursor) {
            pageInfo { hasNextPage endCursor }
            nodes {
              oid
              authoredDate
              messageHeadline
              additions
              deletions
              changedFilesIfAvailable
              author { name user { login } }
            }
          }
        }
      }
    }
  }
  rateLimit { cost remaining }
}

読み方は、外側から順に「リポジトリ → デフォルトブランチ → その先頭のコミット → そこからたどれる履歴(history)を100件」だ。nodes の中に並べたものが、1件ごとに返る項目になる。

項目意味
oidコミットの SHA(短縮形は abbreviatedOid)
authoredDate・committedDate作者日時・コミッター日時
messageHeadlineメッセージの1行目(全文は message)
additions・deletions追加・削除行数
changedFilesIfAvailable変更ファイル数。取得できない場合は null
author { name user { login } }Git に記録された名前と、結び付いた GitHub アカウント
pageInfo続きがあるか(hasNextPage)と、次のページの位置(endCursor)
rateLimitこのクエリが消費したポイントと残り

history には、REST API と同じように since・until・path を指定できる(例:history(first: 100, path: "JsonConverter.bas", since: "2018-01-01T00:00:00+09:00"))。デフォルトブランチ以外を見たいときは、defaultBranchRef の代わりに ref(qualifiedName: "refs/heads/develop") と書く。

Python から呼ぶ

GraphQL API は HTTP の POST なので、requests で呼べる。専用のライブラリは必須ではない。

Python(commits_graphql.py)
"""GitHub GraphQL API でコミット履歴と変更行数を一度に取得する"""
import os
from datetime import datetime, timedelta, timezone

import requests

ENDPOINT = "https://api.github.com/graphql"
JST = timezone(timedelta(hours=9))

QUERY = """
query($owner: String!, $name: String!, $cursor: String) {
  repository(owner: $owner, name: $name) {
    defaultBranchRef {
      target {
        ... on Commit {
          history(first: 100, after: $cursor) {
            pageInfo { hasNextPage endCursor }
            nodes {
              oid
              authoredDate
              messageHeadline
              additions
              deletions
              changedFilesIfAvailable
              author { name user { login } }
            }
          }
        }
      }
    }
  }
  rateLimit { cost remaining }
}
"""


def run_query(session: requests.Session, variables: dict) -> dict:
    r = session.post(ENDPOINT, json={"query": QUERY, "variables": variables}, timeout=30)
    r.raise_for_status()
    body = r.json()
    if body.get("errors"):                    # GraphQL はエラーでも 200 を返す
        raise SystemExit("; ".join(e["message"] for e in body["errors"]))
    return body["data"]


def list_commits(owner: str, name: str):
    """コミットを新しい順に1件ずつ返す(カーソルによるページネーション)"""
    token = os.environ.get("GITHUB_TOKEN")
    if not token:
        raise SystemExit("GraphQL API にはトークンが必要(環境変数 GITHUB_TOKEN)")
    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {token}"

    cursor = None
    while True:
        data = run_query(session, {"owner": owner, "name": name, "cursor": cursor})
        branch = data["repository"]["defaultBranchRef"]
        if branch is None:                    # 空のリポジトリ
            return
        history = branch["target"]["history"]
        yield from history["nodes"]
        if not history["pageInfo"]["hasNextPage"]:
            return
        cursor = history["pageInfo"]["endCursor"]


if __name__ == "__main__":
    count = 0
    for c in list_commits("VBA-tools", "VBA-JSON"):
        when = datetime.fromisoformat(c["authoredDate"].replace("Z", "+00:00")).astimezone(JST)
        files = c["changedFilesIfAvailable"]
        print(f"{when:%Y-%m-%d %H:%M}  {c['author']['name']:<12.12}  {c['oid'][:7]}  "
              f"{'?' if files is None else files:>3} files  "
              f"+{c['additions']:<5} -{c['deletions']:<5} {c['messageHeadline']}")
        count += 1
    print(f"--- {count} 件")

89件すべての変更行数が、1回のリクエストで返る。REST API では90回かかっていた処理だ。

GraphQL で押さえておく点

点内容
エラーの返り方クエリの書き間違いやリポジトリ名の誤りでも、HTTP ステータスは 200 で、本文の errors に内容が入る。ステータスだけを見ていると失敗に気づけない
ページネーションページ番号ではなくカーソルを使う。endCursor を次の after に渡し、hasNextPage が false になるまで繰り返す。1回に取れるのは最大100件
レート制限回数ではなくポイントで数える(1時間 5,000ポイント)。このクエリは1回あたり1ポイント程度で、rateLimit { cost } で実際の値を確認できる
日時REST API と同じく UTC の ISO 8601 形式で返る

クエリを試し書きするときは、GitHub Docs の「エクスプローラー」が便利だ。ブラウザー上で項目を補完しながらクエリを実行できる。

GitHub CLI(gh)で取得する

GitHub CLI は、GitHub 公式のコマンドラインツールだ。gh api サブコマンドを使うと、認証済みの状態で REST API や GraphQL API を呼べる。Windows では winget でインストールできる。

ターミナル
winget install --id GitHub.cli
gh auth login

gh auth login を実行すると、ブラウザーでのサインインに進む。サインイン後はトークンを CLI が OS の資格情報の保管場所に保存するので、自分でトークンを発行・保管する必要がない。状態は gh auth status で確認できる。

コマンド1行で確認する

ターミナル
gh api "repos/VBA-tools/VBA-JSON/commits?per_page=5" --jq ".[] | [.sha[0:7], .commit.author.date, .commit.author.name] | @tsv"
実行結果
06b6c45	2019-01-28T16:19:54Z	Tim Hall
1e49ba8	2019-01-28T16:05:23Z	Tim Hall
e0f1a77	2019-01-28T16:04:26Z	Tim Hall
652ad8c	2018-08-30T20:16:59Z	Tim Hall
946f126	2018-06-07T14:52:32Z	Tim Hall

--jq は、返ってきた JSON から項目を抜き出すオプションだ(jq を別途インストールする必要はない)。--paginate を付けると、Link ヘッダーをたどって全ページを取得する。

Python から呼ぶ

Python からは、gh を子プロセスとして実行し、出力を読む。日本時間への変換やメッセージの1行目の切り出しは、Python 側で行う方が書きやすい。

Python(commits_gh.py)
"""GitHub CLI(gh api)を呼び出してコミット履歴を取得して表示する"""
import json
import subprocess
from datetime import datetime, timedelta, timezone

JST = timezone(timedelta(hours=9))
# 1コミットを1行の JSON 配列にして出力させる
JQ = ".[] | [.sha, .commit.author.name, .commit.author.date, .commit.message] | @json"


def list_commits(repo: str):
    r = subprocess.run(
        ["gh", "api", f"repos/{repo}/commits?per_page=100", "--paginate", "--jq", JQ],
        capture_output=True, text=True, encoding="utf-8",
    )
    if r.returncode != 0:
        raise SystemExit(f"gh api が失敗した: {r.stderr.strip()}")
    for line in r.stdout.splitlines():
        if line.strip():
            yield json.loads(line)


if __name__ == "__main__":
    for sha, name, date, message in list_commits("VBA-tools/VBA-JSON"):
        when = datetime.fromisoformat(date.replace("Z", "+00:00")).astimezone(JST)
        subject = (message.splitlines() or [""])[0]
        print(f"{when:%Y-%m-%d %H:%M}  {name:<12.12}  {sha[:7]}  {subject}")

コマンドを文字列ではなくリストで渡しているので、シェルの引用符の違い(PowerShell・コマンドプロンプト・bash)に悩まされない。

💡 gh のトークンを他のスクリプトで使う

gh auth token を実行すると、CLI が保管しているトークンが表示される。PART 03 のスクリプトで環境変数の代わりにこれを使うこともできる(subprocess.run(["gh", "auth", "token"], capture_output=True, text=True).stdout.strip())。逆に、CI などサインインできない環境で gh を使うときは、環境変数 GH_TOKEN にトークンを設定する。

4つの方法の使い分け

PART 03 の方法と合わせて、Python から API 方式で取得する方法は4つになった。

方法向いている場面気を付ける点
REST API + requests(PART 03)仕組みを理解したい。依存を増やしたくない。他の言語にも移したいヘッダーやページネーションを自分で書く
PyGithubコミット以外(Issue、プルリクエスト、リリースなど)も扱う。短く書きたいどこでリクエストが飛ぶかが見えにくい
GraphQL変更行数のように、REST では追加リクエストが必要な項目をまとめて取りたいトークン必須。クエリの書き方を覚える必要がある
GitHub CLIその場で確認したい。トークンの管理を任せたい実行する PC ごとに gh のインストールとサインインが必要

プライベートリポジトリの場合

🔒 この回のコードで変わる点

  • PyGithub:コードの変更は不要。環境変数 GITHUB_TOKEN に、対象リポジトリの Contents: Read-only を付けたトークンを設定する。権限がないと UnknownObjectException(404)が発生する
  • GraphQL:もともとトークンが必須。権限がないリポジトリを指定すると、errors に「Could not resolve to a Repository」という内容が返る
  • GitHub CLI:gh auth login でサインインしたアカウントが読めるリポジトリなら、そのまま取得できる。組織が SAML シングルサインオンを使っている場合は、サインインの途中で組織の承認を求められる
  • GitHub Enterprise Server の場合、PyGithub は Github(base_url="https://ホスト名/api/v3", auth=...)、GraphQL は https://ホスト名/api/graphql、GitHub CLI は gh auth login --hostname ホスト名 を使う

✅ 次の記事では…

PART 05 では、API を使わず、ローカルクローンに対して git log を実行する方法と GitPython を使う方法を扱う。レート制限がなく、変更行数も一度に取れる。

→ PART 05 — Pythonでローカルクローンを操作する(git log・GitPython)へ