3つの方法の位置づけ
この回で扱う3つは、どれも最終的には GitHub の API を呼んでいる。違うのは、どこまでを道具に任せるかだ。
| 方法 | 中身 | 任せられること | トークン |
|---|---|---|---|
| PyGithub | REST API を包んだ Python ライブラリ | ヘッダー、ページネーション、JSON からオブジェクトへの変換 | 公開リポジトリなら省略可 |
| GraphQL API | REST とは別の API。欲しい項目を問い合わせ文で指定する | 項目の取捨選択。関連する情報をまとめて取得 | 必須 |
GitHub CLI(gh) | GitHub 公式のコマンド。gh api で REST も GraphQL も呼べる | 認証(トークンの保管)、ページネーション、JSON の整形 | gh auth login で一度サインインする |
PyGithub で取得する
PyGithub は、GitHub の REST API を Python のオブジェクトとして扱えるようにしたライブラリだ。
pip install PyGithubお題の実装は次のとおり。PART 03 で自分で書いたヘッダーの設定とページネーションが、すべてなくなっている。
"""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 の JSON | PyGithub |
|---|---|---|
| SHA | sha | c.sha |
| 作者名 | commit.author.name | c.commit.author.name |
| 日時 | commit.author.date(文字列) | c.commit.author.date(タイムゾーン付きの datetime) |
| メッセージ | commit.message | c.commit.message |
| GitHub のユーザー名 | author.login | c.author.login(c.author が None のことがある) |
| 変更行数 | (詳細の API)stats.additions | c.stats.additions・c.stats.deletions |
絞り込み
get_commits の引数は、REST API のパラメーターと同じ名前だ。日時は文字列ではなく datetime で渡す。
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(追加・削除行数)は一覧の中で指定できるので、コミットごとの追加リクエストが要らない - トークンが必須。公開リポジトリでも、トークンなしでは呼べない
クエリ
お題に発展課題(変更ファイル数と行数)を加えたクエリは次のようになる。
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 で呼べる。専用のライブラリは必須ではない。
"""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 logingh 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 側で行う方が書きやすい。
"""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 を使う方法を扱う。レート制限がなく、変更行数も一度に取れる。