完成イメージと準備
この回で作るスクリプトは、リポジトリ名を渡すとコミット履歴を新しい順に表示する。
> python commits_rest.py VBA-tools/VBA-JSON --max 8
2019-01-29 01:19 Tim Hall 06b6c45 Update license
2019-01-29 01:05 Tim Hall 1e49ba8 v2.3.1
2019-01-29 01:04 Tim Hall e0f1a77 Update vba-utc to v1.0.6
2018-08-31 05:16 Tim Hall 652ad8c Update README.md
2018-06-07 23:52 Tim Hall 946f126 v2.3.0
2018-06-07 23:49 Tim Hall 284dc72 Merge pull request #101 from VBA-tools/append
2018-06-07 23:48 Tim Hall 45aff20 Fix failing test on Mac
2018-06-07 22:12 Tim Hall bc913ff Cleanup
--- 8 件必要なライブラリは requests だけだ。
pip install requests公開リポジトリが対象なら、トークンがなくても動く。PART 02 の手順で環境変数 GITHUB_TOKEN を設定してあれば、自動的にトークンを使う。
コミット一覧のエンドポイント
コミットの一覧は、次の URL に GET リクエストを送って取得する。
GET https://api.github.com/repos/{owner}/{repo}/commitsクエリパラメーターで、取得する範囲を指定できる。すべて省略可能だ。
| パラメーター | 意味 | 例 |
|---|---|---|
sha | 起点にするブランチ名・タグ名・コミットの SHA。省略するとデフォルトブランチ | develop |
path | このパス(ファイルまたはフォルダー)を変更したコミットだけ | JsonConverter.bas |
author | 作者。GitHub のユーザー名またはメールアドレス | timhall |
since | この日時以降。ISO 8601 形式 | 2018-01-01T00:00:00+09:00 |
until | この日時以前。ISO 8601 形式 | 2018-12-31T23:59:59+09:00 |
per_page | 1ページの件数。既定は30、最大は100 | 100 |
page | ページ番号。既定は1 | 2 |
レスポンスは、コミットを1件1要素とした配列だ。お題に必要な部分だけを抜き出すと、次のような構造になっている。
{
"sha": "06b6c45a2e8086a7a761f00bead7460852d6b602",
"commit": {
"author": { "name": "Tim Hall", "email": "...", "date": "2019-01-28T16:19:54Z" },
"committer": { "name": "Tim Hall", "email": "...", "date": "2019-01-28T16:19:54Z" },
"message": "Update license",
"verification": { "verified": false, "reason": "unsigned" }
},
"html_url": "https://github.com/VBA-tools/VBA-JSON/commit/06b6c45a...",
"author": { "login": "timhall", "id": 1211148 },
"committer": { "login": "timhall", "id": 1211148 },
"parents": [ { "sha": "1e49ba826b979d1851029dc965ecb6a3ead2a32c" } ]
}紛らわしいのは、author が2か所にあることだ。
commit.author:Git に記録されている名前・メールアドレス・日時。必ず入っている- 外側の
author:そのメールアドレスに結び付いた GitHub アカウント。結び付くアカウントがなければnullになる
お題の「作者」と「日時」には、必ず値が入っている commit.author を使う。
スクリプト全体
次のコードを commits_rest.py として保存する。
"""GitHub REST API でコミット履歴を取得して表示する"""
import argparse
import os
import time
from datetime import datetime, timedelta, timezone
import requests
API = "https://api.github.com"
API_VERSION = "2022-11-28"
JST = timezone(timedelta(hours=9))
def make_session() -> requests.Session:
s = requests.Session()
s.headers.update({
"Accept": "application/vnd.github+json",
"X-GitHub-Api-Version": API_VERSION,
"User-Agent": "commit-history-sample",
})
token = os.environ.get("GITHUB_TOKEN")
if token: # 公開リポジトリならトークンなしでも動く(1時間60回まで)
s.headers["Authorization"] = f"Bearer {token}"
return s
def get(session: requests.Session, url: str, params: dict | None = None) -> requests.Response:
"""1回のリクエスト。レート制限に当たったら短時間だけ待って再試行する"""
for _ in range(3):
r = session.get(url, params=params, timeout=30)
if r.status_code in (403, 429):
if r.headers.get("Retry-After"): # セカンダリレート制限
wait = int(r.headers["Retry-After"])
elif r.headers.get("X-RateLimit-Remaining") == "0": # プライマリレート制限
wait = int(r.headers["X-RateLimit-Reset"]) - int(time.time()) + 1
else:
wait = None
if wait is not None:
if wait > 120:
reset = datetime.now(JST) + timedelta(seconds=wait)
raise SystemExit(f"レート制限に達した。{reset:%H:%M} 以降に再実行する")
time.sleep(max(wait, 1))
continue
if r.status_code == 404:
raise SystemExit("404: リポジトリ名が違うか、非公開リポジトリを読む権限がない")
r.raise_for_status()
return r
raise SystemExit("再試行の上限に達した")
def list_commits(session: requests.Session, repo: str, **filters):
"""コミットを新しい順に1件ずつ返す(ページネーション対応)"""
url = f"{API}/repos/{repo}/commits"
params = {"per_page": 100, **{k: v for k, v in filters.items() if v}}
while url:
r = get(session, url, params)
yield from r.json()
url = r.links.get("next", {}).get("url") # Link ヘッダーの rel="next"
params = None # next の URL は条件を含んでいる
def get_stats(session: requests.Session, repo: str, sha: str) -> tuple[int, int, int]:
"""コミット1件の変更ファイル数・追加行数・削除行数(1件につき1リクエスト)"""
d = get(session, f"{API}/repos/{repo}/commits/{sha}").json()
return len(d["files"]), d["stats"]["additions"], d["stats"]["deletions"]
def to_row(c: dict) -> tuple[str, str, str, str]:
a = c["commit"]["author"]
when = datetime.fromisoformat(a["date"].replace("Z", "+00:00")).astimezone(JST)
subject = (c["commit"]["message"].splitlines() or [""])[0]
return when.strftime("%Y-%m-%d %H:%M"), a["name"], c["sha"][:7], subject
def main() -> None:
p = argparse.ArgumentParser(description="コミット履歴を表示する")
p.add_argument("repo", help="OWNER/REPO 形式(例: VBA-tools/VBA-JSON)")
p.add_argument("--branch", help="ブランチ名・タグ名・SHA(省略時はデフォルトブランチ)")
p.add_argument("--since", help="この日時以降(例: 2018-01-01T00:00:00+09:00)")
p.add_argument("--until", help="この日時以前")
p.add_argument("--author", help="GitHub のユーザー名またはメールアドレス")
p.add_argument("--path", help="このパスを変更したコミットだけ")
p.add_argument("--max", type=int, default=0, help="表示する最大件数(0 は全件)")
p.add_argument("--stats", action="store_true", help="変更ファイル数と行数も表示する")
args = p.parse_args()
session = make_session()
commits = list_commits(session, args.repo, sha=args.branch, since=args.since,
until=args.until, author=args.author, path=args.path)
count = 0
for c in commits:
when, name, sha, subject = to_row(c)
line = f"{when} {name:<12.12} {sha} "
if args.stats:
files, add, dele = get_stats(session, args.repo, c["sha"])
line += f"{files:>3} files +{add:<5} -{dele:<5} "
print(line + subject)
count += 1
if args.max and count >= args.max:
break
print(f"--- {count} 件")
if __name__ == "__main__":
main()コードのポイント
ヘッダーは Session にまとめる
requests.Session にヘッダーを設定しておくと、以降のリクエストすべてに付く。接続も使い回されるので、ページをたどるときに速い。付けているヘッダーは4つだ。
| ヘッダー | 役割 |
|---|---|
Accept: application/vnd.github+json | GitHub の JSON 形式で受け取る(公式が推奨している指定) |
X-GitHub-Api-Version | API のバージョンを固定する(PART 02) |
User-Agent | GitHub の API は User-Agent のないリクエストを拒否する。requests は既定値を付けるが、何のプログラムかわかる名前にしておく |
Authorization: Bearer トークン | 認証。環境変数にトークンがあるときだけ付ける |
ページネーションは Link ヘッダーをたどる
コミットが100件を超えるリポジトリでは、1回のリクエストで全件は返らない。続きがあるとき、レスポンスの Link ヘッダーに次のページの URL が入る。
link: <https://api.github.com/repositories/25739947/commits?per_page=30&page=2>; rel="next",
<https://api.github.com/repositories/25739947/commits?per_page=30&page=3>; rel="last"requests はこのヘッダーを解析して r.links に入れてくれるので、rel="next" の URL がなくなるまで繰り返せばよい。ページ番号を自分で数える方法より確実で、他の一覧系 API にも同じ書き方が使える。list_commits はジェネレーターにしてあるので、--max 8 のように途中で打ち切ると、それ以降のページは取得しない。
日時は UTC で返る
commit.author.date は 2019-01-28T16:19:54Z のように UTC で返る(末尾の Z が UTC を表す)。日本時間にするには9時間進める必要があり、to_row では astimezone(JST) で変換している。変換を忘れると、日付が1日ずれるコミットが出てくる。
並び順は「日時の降順」とは限らない
一覧は、起点のコミットから親をたどった順に返る。ブランチを長く育ててからマージした場合などは、古い日時のコミットが新しい日時のコミットより前に出ることがある。日時順に並べたいときは、取得したあとで並べ替える。
レート制限に当たったときの動き
get では、403・429 が返ったときにヘッダーを見て、待ち時間が2分以内なら待って再試行し、それより長ければ再開できる時刻を表示して終了する。トークンなしで上限(1時間60回)に達した場合は後者になる。
条件を絞って取得する
オプションを付けると、エンドポイントのパラメーターにそのまま渡る。たとえば「2018年以降に JsonConverter.bas を変更したコミット」は次のように取得する。
> python commits_rest.py VBA-tools/VBA-JSON --path JsonConverter.bas --since 2018-01-01T00:00:00+09:00since と until にタイムゾーンを付けずに 2018-01-01T00:00:00Z と書くと UTC として扱われる。日本時間で区切りたいときは、例のように +09:00 を付ける。
発展:変更ファイル数と行数を付ける
一覧のレスポンスには、変更したファイルや行数は入っていない。これらは、コミット1件を取得する別のエンドポイントで得られる。
GET https://api.github.com/repos/{owner}/{repo}/commits/{sha}レスポンスには、一覧と同じ項目に加えて stats(追加・削除・合計の行数)と files(変更したファイルの配列)が入る。--stats を付けると、get_stats がコミットごとにこのエンドポイントを呼ぶ。
> python commits_rest.py VBA-tools/VBA-JSON --path JsonConverter.bas --since 2018-01-01T00:00:00+09:00 --stats
2019-01-29 01:05 Tim Hall 1e49ba8 2 files +1 -1 v2.3.1
2019-01-29 01:04 Tim Hall e0f1a77 2 files +16 -5 Update vba-utc to v1.0.6
2018-06-07 23:52 Tim Hall 946f126 2 files +1 -1 v2.3.0
2018-06-07 22:12 Tim Hall bc913ff 1 files +5 -6 Cleanup
2018-06-07 22:06 Tim Hall cf4e164 2 files +95 -100 Inline clsStringAppend
2018-01-27 03:13 philip_swann 17ceebe 4 files +308 -141 json_BufferAppend replaced with clsStringAppend
2018-04-26 22:01 Tim Hall 0af3e4d 2 files +1 -1 v2.2.4
2018-04-26 22:01 Tim Hall f94b88e 1 files +6 -6 Update VBA-UTC to v1.0.5
--- 8 件6行目のコミット(1月27日)が、4月26日のコミットより前に出ている。先ほど説明した「日時の降順とは限らない」の実例だ。
⚠️ コミットの数だけリクエストが増える
この例は一覧1回+詳細8回で、合計9回のリクエストになる。89件すべてに --stats を付けると90回となり、トークンなしの上限(1時間60回)を超える。件数が多いときは、条件で絞るか、トークンを使うか、行数を一度に取れる GraphQL(PART 04)やローカル方式(PART 05)を選ぶ。
なお、1件のコミットで変更ファイルが非常に多い場合、files は1回のレスポンスに最大300件までしか入らない。その場合も stats の行数はコミット全体の値になっている。
CSV に出力する
結果を Excel で開きたいときは、CSV に書き出す。main の表示部分を次のように置き換える。
import csv
with open("commits.csv", "w", newline="", encoding="utf-8-sig") as f:
w = csv.writer(f)
w.writerow(["日時", "作者", "SHA", "メッセージ"])
for c in list_commits(make_session(), "VBA-tools/VBA-JSON"):
w.writerow(to_row(c))文字コードを utf-8-sig(BOM 付き UTF-8)にしておくと、Excel でダブルクリックして開いても日本語が化けない。
プライベートリポジトリの場合
🔒 この回のコードで変わる点
- コードの変更は不要。環境変数
GITHUB_TOKENに、対象リポジトリの Contents: Read-only を付けたトークン(PART 02)を設定するだけでよい - トークンがない、または権限が足りないと
404が返る。このスクリプトは「リポジトリ名が違うか、権限がない」と表示して終了する - GitHub Enterprise Server を使っている場合は、定数
APIをhttps://ホスト名/api/v3に変える
つまずきやすい点
| 症状 | 原因と対処 |
|---|---|
401 Bad credentials | トークンの値が違う、または期限切れ。環境変数を設定したあと、ターミナルを開き直したかも確認する |
404 Not Found | 所有者名/リポジトリ名 の打ち間違い、または非公開リポジトリで権限がない |
403 で「rate limit exceeded」 | レート制限。トークンを設定すると上限が 5,000回になる |
409 Conflict | リポジトリが空(コミットが1件もない) |
| 30件しか取れない | per_page を指定しておらず、ページもたどっていない。この回の list_commits を使う |
| 社内ネットワークで接続できない | プロキシが必要。環境変数 HTTPS_PROXY に http://proxy.example.co.jp:8080 の形式で設定すると requests が使う |
✅ 次の記事では…
PART 04 では、同じお題を PyGithub・GraphQL・GitHub CLI で実装する。ライブラリを使うとどこまで短くなるか、GraphQL で変更行数を一度に取るとどうなるかを比べる。