codeyear 0.2.14__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,590 @@
1
+ """Generate a CodeYear report from public GitHub data.
2
+
3
+ This is an optional online mode. The regular ``scan`` command still reads
4
+ local git and never uploads anything. This module only reads public
5
+ repositories through the GitHub REST API.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import os
12
+ import re
13
+ import sys
14
+ import time
15
+ import urllib.error
16
+ import urllib.parse
17
+ import urllib.request
18
+ from concurrent.futures import ThreadPoolExecutor
19
+ from datetime import datetime, timedelta, timezone, tzinfo
20
+ from pathlib import Path
21
+ from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
22
+
23
+ from . import i18n
24
+ from .languages import language_for
25
+ from .runner import render, report_path
26
+ from .scanner import Commit, FileChange, RepoResult
27
+ from .stats import ReportStats, build_stats, fmt_human, fmt_int
28
+
29
+ API = "https://api.github.com"
30
+ DETAIL_WORKERS = 8
31
+ CACHE_VERSION = 1
32
+ CACHE_MAX = 5000
33
+
34
+
35
+ def default_cache_dir() -> Path:
36
+ return Path.home() / ".cache" / "codeyear"
37
+
38
+ _OFFSET_RE = re.compile(
39
+ r"^(?:UTC|GMT)?\s*([+-])\s*(\d{1,2})(?::?(\d{2}))?$", re.I
40
+ )
41
+ _FALLBACK_ZONES: dict[str, int] = {
42
+ "utc": 0,
43
+ "gmt": 0,
44
+ "etc/utc": 0,
45
+ "europe/london": 0,
46
+ "europe/berlin": 60,
47
+ "europe/paris": 60,
48
+ "asia/shanghai": 480,
49
+ "asia/chongqing": 480,
50
+ "asia/hong_kong": 480,
51
+ "asia/taipei": 480,
52
+ "asia/singapore": 480,
53
+ "asia/tokyo": 540,
54
+ "asia/seoul": 540,
55
+ "Asia/Kolkata".lower(): 330,
56
+ "america/new_york": -300,
57
+ "america/chicago": -360,
58
+ "america/denver": -420,
59
+ "america/los_angeles": -480,
60
+ }
61
+
62
+
63
+ def _parse_tz(tz: str | tzinfo | None = None) -> tzinfo | None:
64
+ if isinstance(tz, tzinfo):
65
+ return tz
66
+ spec = (
67
+ tz
68
+ or os.environ.get("CODEYEAR_TZ")
69
+ or os.environ.get("TZ")
70
+ or ""
71
+ ).strip()
72
+ if not spec:
73
+ return None
74
+ if spec.upper() in {"Z", "UTC", "GMT"}:
75
+ return timezone.utc
76
+ m = _OFFSET_RE.match(spec)
77
+ if m:
78
+ sign = -1 if m.group(1) == "-" else 1
79
+ hours = int(m.group(2))
80
+ minutes = int(m.group(3) or 0)
81
+ if hours <= 14 and minutes < 60:
82
+ return timezone(sign * timedelta(hours=hours, minutes=minutes))
83
+ try:
84
+ return ZoneInfo(spec)
85
+ except (ZoneInfoNotFoundError, KeyError, ValueError):
86
+ mins = _FALLBACK_ZONES.get(spec.lower())
87
+ if mins is not None:
88
+ return timezone(timedelta(minutes=mins))
89
+ return None
90
+
91
+
92
+ def _load_cache(path: Path | None) -> dict:
93
+ if path is None or not path.exists():
94
+ return {}
95
+ try:
96
+ data = json.loads(path.read_text(encoding="utf-8"))
97
+ except (OSError, ValueError):
98
+ return {}
99
+ if not isinstance(data, dict) or data.get("version") != CACHE_VERSION:
100
+ return {}
101
+ details = data.get("details")
102
+ return details if isinstance(details, dict) else {}
103
+
104
+
105
+ def _save_cache(path: Path | None, details: dict) -> None:
106
+ if path is None:
107
+ return
108
+ try:
109
+ path.parent.mkdir(parents=True, exist_ok=True)
110
+ if len(details) > CACHE_MAX:
111
+ details = dict(list(details.items())[-CACHE_MAX:])
112
+ path.write_text(
113
+ json.dumps(
114
+ {"version": CACHE_VERSION, "details": details},
115
+ ensure_ascii=False,
116
+ ),
117
+ encoding="utf-8",
118
+ )
119
+ except OSError:
120
+ pass
121
+
122
+
123
+ def _dt(
124
+ value: str | None, tz: str | tzinfo | None = None
125
+ ) -> datetime | None:
126
+ if not value:
127
+ return None
128
+ try:
129
+ parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
130
+ # GitHub timestamps are UTC. Convert to the requested timezone (or the
131
+ # machine's local timezone) so hour-of-day and late-night statistics
132
+ # match the local report.
133
+ if parsed.tzinfo is not None:
134
+ target_tz = _parse_tz(tz)
135
+ parsed = parsed.astimezone(target_tz).replace(tzinfo=None)
136
+ return parsed
137
+ except ValueError:
138
+ return None
139
+
140
+
141
+ class GitHubAPI:
142
+ def __init__(self, token: str | None = None) -> None:
143
+ self.token = token or os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
144
+ self.remaining: int | None = None
145
+
146
+ def get(self, path: str, params: dict | None = None):
147
+ url = API + path
148
+ if params:
149
+ url += "?" + urllib.parse.urlencode(params)
150
+ request = urllib.request.Request(
151
+ url,
152
+ headers={
153
+ "Accept": "application/vnd.github+json",
154
+ "User-Agent": "CodeYear",
155
+ "X-GitHub-Api-Version": "2022-11-28",
156
+ },
157
+ )
158
+ if self.token:
159
+ request.add_header("Authorization", f"Bearer {self.token}")
160
+ try:
161
+ with urllib.request.urlopen(request, timeout=30) as response:
162
+ remaining = response.headers.get("X-RateLimit-Remaining")
163
+ if remaining is not None:
164
+ self.remaining = int(remaining)
165
+ if response.status == 202:
166
+ return None
167
+ body = response.read().decode("utf-8")
168
+ return json.loads(body) if body else None
169
+ except urllib.error.HTTPError as exc:
170
+ if exc.code == 404:
171
+ return None
172
+ if exc.code == 403 and (exc.headers.get("X-RateLimit-Remaining") == "0"):
173
+ raise RuntimeError(
174
+ "GitHub API 已限流。请稍后重试,或设置 GITHUB_TOKEN / --token。"
175
+ ) from exc
176
+ raise
177
+
178
+ def paginate(self, path: str, params: dict | None = None, pages: int = 10) -> list:
179
+ items: list = []
180
+ for page in range(1, pages + 1):
181
+ query = dict(params or {})
182
+ query.update({"per_page": 100, "page": page})
183
+ data = self.get(path, query)
184
+ if not data:
185
+ break
186
+ items.extend(data)
187
+ if len(data) < 100:
188
+ break
189
+ return items
190
+
191
+
192
+ def _repos(
193
+ api: GitHubAPI,
194
+ username: str,
195
+ since: datetime,
196
+ include_forks: bool,
197
+ *,
198
+ tz: str | tzinfo | None = None,
199
+ ) -> list[dict]:
200
+ target_tz = _parse_tz(tz)
201
+ repos: list[dict] = []
202
+ for page in range(1, 11):
203
+ data = api.get(f"/users/{username}/repos", {
204
+ "type": "owner", "sort": "pushed", "direction": "desc",
205
+ "per_page": 100, "page": page,
206
+ })
207
+ if not data:
208
+ break
209
+ for repo in data:
210
+ if repo.get("private"):
211
+ continue
212
+ if repo.get("fork") and not include_forks:
213
+ continue
214
+ pushed = _dt(repo.get("pushed_at"), tz=target_tz)
215
+ if pushed and pushed < since:
216
+ return repos
217
+ repos.append(repo)
218
+ if len(data) < 100:
219
+ break
220
+ return repos
221
+
222
+
223
+ def _commits(
224
+ api: GitHubAPI,
225
+ repo: dict,
226
+ username: str,
227
+ year: int,
228
+ limit: int,
229
+ quiet: bool,
230
+ cache: dict | None = None,
231
+ *,
232
+ tz: str | tzinfo | None = None,
233
+ ) -> list[Commit]:
234
+ target_tz = _parse_tz(tz)
235
+ full = repo["full_name"]
236
+ # Pad the UTC window by a day on each side; actual filtering below uses
237
+ # the local year, so commits near midnight in non-UTC zones are kept.
238
+ since = f"{year - 1}-12-31T00:00:00Z"
239
+ until = f"{year + 1}-01-02T00:00:00Z"
240
+ listed: list[dict] = []
241
+ # A busy repository can exceed 1,000 commits in one year; keep paging
242
+ # until the caller's budget is reached or GitHub runs out of pages.
243
+ for page in range(1, 101):
244
+ data = api.get(f"/repos/{full}/commits", {
245
+ "author": username, "since": since, "until": until,
246
+ "per_page": 100, "page": page,
247
+ })
248
+ if not data:
249
+ break
250
+ listed.extend(data)
251
+ if len(data) < 100 or len(listed) >= limit:
252
+ break
253
+
254
+ items = listed[:limit]
255
+ keys = [f"{full}@{item['sha']}" for item in items]
256
+ details: list[dict | None] = []
257
+ missing: list[tuple[int, dict]] = []
258
+ for index, (item, key) in enumerate(zip(items, keys)):
259
+ if cache is not None and key in cache:
260
+ details.append(cache[key])
261
+ else:
262
+ details.append(None)
263
+ missing.append((index, item))
264
+
265
+ if missing:
266
+ if api.remaining is not None and api.remaining < len(missing) + 5:
267
+ raise RuntimeError(i18n.tr(
268
+ "GitHub API 额度不足,请使用更高额度的 token(如 CODEYEAR_TOKEN)后重试。"
269
+ ))
270
+
271
+ def fetch_detail(entry: tuple[int, dict]):
272
+ idx, item = entry
273
+ detail = api.get(f"/repos/{full}/commits/{item['sha']}")
274
+ if cache is not None and detail:
275
+ cache[keys[idx]] = detail
276
+ return detail
277
+
278
+ # Commit details are independent; a small pool cuts wall time without
279
+ # changing the request count or adding dependencies.
280
+ with ThreadPoolExecutor(max_workers=DETAIL_WORKERS) as pool:
281
+ fetched = list(pool.map(fetch_detail, missing))
282
+ for (index, _item), detail in zip(missing, fetched):
283
+ details[index] = detail
284
+
285
+ commits: list[Commit] = []
286
+ for item, detail in zip(items, details):
287
+ if not detail:
288
+ continue
289
+ # Match the local scanner's --no-merges behavior.
290
+ if len(detail.get("parents") or []) > 1:
291
+ continue
292
+ author_date = ((detail.get("commit") or {}).get("author") or {}).get("date")
293
+ dt = _dt(author_date, tz=target_tz)
294
+ if dt is None:
295
+ dt = _dt((item.get("commit") or {}).get("author", {}).get("date"), tz=target_tz)
296
+ if dt is None or dt.year != year:
297
+ continue
298
+ message = ((detail.get("commit") or {}).get("message") or "").splitlines()
299
+ subject = message[0].strip() if message else ""
300
+ stats = detail.get("stats") or {}
301
+ changes: list[FileChange] = []
302
+ for file in detail.get("files") or []:
303
+ path = file.get("filename") or ""
304
+ lang = language_for(path)
305
+ if lang is None:
306
+ continue
307
+ f_add = int(file.get("additions", 0))
308
+ f_del = int(file.get("deletions", 0))
309
+ changes.append(FileChange(
310
+ path=path, lang=lang,
311
+ lines=f_add + f_del,
312
+ added=f_add,
313
+ deleted=f_del,
314
+ ))
315
+ commits.append(Commit(
316
+ repo=full,
317
+ hash=item["sha"],
318
+ dt=dt,
319
+ subject=subject[:200],
320
+ added=int(stats.get("additions", 0)),
321
+ deleted=int(stats.get("deletions", 0)),
322
+ files=len(detail.get("files") or []),
323
+ author_email=username,
324
+ author_name=username,
325
+ changes=changes,
326
+ ))
327
+ if not quiet and commits:
328
+ print(i18n.tr(
329
+ " {repo} · {count} 次提交", repo=full, count=len(commits),
330
+ ), file=sys.stderr)
331
+ return commits
332
+
333
+
334
+ def _total_commits(api: GitHubAPI, full: str, username: str) -> int:
335
+ for _ in range(3):
336
+ data = api.get(f"/repos/{full}/stats/contributors")
337
+ if isinstance(data, list):
338
+ for contributor in data:
339
+ author = contributor.get("author") or {}
340
+ if (author.get("login") or "").lower() == username.lower():
341
+ return sum(int(week.get("c", 0)) for week in contributor.get("weeks", []))
342
+ return 0
343
+ time.sleep(1)
344
+ return 0
345
+
346
+
347
+ def fetch_stats(
348
+ username: str,
349
+ year: int,
350
+ *,
351
+ token: str | None = None,
352
+ max_commits: int = 200,
353
+ include_forks: bool = False,
354
+ quiet: bool = False,
355
+ cache_path: Path | None = None,
356
+ tz: str | tzinfo | None = None,
357
+ ) -> tuple[ReportStats, list[str], str]:
358
+ api = GitHubAPI(token)
359
+ target_tz = _parse_tz(tz)
360
+ cache = _load_cache(cache_path)
361
+ if not api.token and max_commits > 30:
362
+ max_commits = 30
363
+ if not quiet:
364
+ print(" ! " + i18n.tr(
365
+ "未设置 GITHUB_TOKEN,最多拉取 30 条提交。"
366
+ ), file=sys.stderr)
367
+
368
+ try:
369
+ user = api.get(f"/users/{urllib.parse.quote(username)}")
370
+ if not user:
371
+ raise RuntimeError(i18n.tr(
372
+ "找不到 GitHub 用户: {username}", username=username,
373
+ ))
374
+ login = user.get("login") or username
375
+ display_name = user.get("name") or login
376
+ # Pad the repo cutoff by 1 day so repos pushed near Jan 1 UTC are not
377
+ # skipped when converted to negative-offset timezones.
378
+ since = datetime(year - 1, 12, 31)
379
+
380
+ if not quiet:
381
+ print(f"CodeYear · github.com/{login} · {year}", file=sys.stderr)
382
+ repos = _repos(api, login, since, include_forks, tz=target_tz)
383
+ except RuntimeError as exc:
384
+ raise RuntimeError(i18n.tr(
385
+ "GitHub API 错误: {exc}", exc=exc,
386
+ )) from exc
387
+
388
+ results: list[RepoResult] = []
389
+ warnings: list[str] = []
390
+ total = 0
391
+ for index, repo in enumerate(repos, 1):
392
+ if total >= max_commits:
393
+ warnings.append(i18n.tr(
394
+ "已达到 --max-commits 上限({limit})", limit=max_commits,
395
+ ))
396
+ break
397
+ full = repo["full_name"]
398
+ if not quiet:
399
+ print(f"[{index}/{len(repos)}] {full}", file=sys.stderr)
400
+ try:
401
+ commits = _commits(
402
+ api, repo, login, year, max_commits - total, quiet,
403
+ cache=cache, tz=target_tz,
404
+ )
405
+ except RuntimeError as exc:
406
+ warnings.append(str(exc))
407
+ break
408
+ if not commits:
409
+ continue
410
+ total += len(commits)
411
+ try:
412
+ repo_total = _total_commits(api, full, login)
413
+ except RuntimeError as exc:
414
+ warnings.append(str(exc))
415
+ repo_total = 0
416
+ results.append(RepoResult(
417
+ path=Path(full),
418
+ name=full,
419
+ commits=commits,
420
+ remote=repo.get("html_url"),
421
+ readme_line=repo.get("description") or "",
422
+ root=full,
423
+ root_dt=_dt(repo.get("created_at"), tz=target_tz),
424
+ total_commits=repo_total or len(commits),
425
+ tags_in_year=0,
426
+ ))
427
+
428
+ if not results:
429
+ _save_cache(cache_path, cache)
430
+ raise RuntimeError(i18n.tr(
431
+ "{login} 在 {year} 年没有找到公开提交。", login=login, year=year,
432
+ ))
433
+
434
+ _save_cache(cache_path, cache)
435
+
436
+ stats = build_stats(
437
+ year=year,
438
+ root=f"https://github.com/{login}",
439
+ repos=results,
440
+ warnings=warnings,
441
+ identity=(login, display_name),
442
+ )
443
+ if stats.commit_count == 0:
444
+ raise RuntimeError(i18n.tr(
445
+ "{login} 在 {year} 年没有找到公开提交。", login=login, year=year,
446
+ ))
447
+ return stats, warnings, login
448
+
449
+
450
+ def run(
451
+ username: str,
452
+ year: int,
453
+ out_dir: str | Path,
454
+ *,
455
+ token: str | None = None,
456
+ max_commits: int = 200,
457
+ include_forks: bool = False,
458
+ open_report: bool = False,
459
+ quiet: bool = False,
460
+ theme: str = "paper",
461
+ card_only: bool = False,
462
+ profile_repo: str | Path | None = None,
463
+ push_profile: bool = False,
464
+ fallback_previous: bool = False,
465
+ cache_dir: str | Path | None = None,
466
+ no_cache: bool = False,
467
+ lang: str = "zh",
468
+ tz: str | None = None,
469
+ ) -> int:
470
+ cache_path = None
471
+ if not no_cache:
472
+ effective_dir = Path(cache_dir) if cache_dir else default_cache_dir()
473
+ safe_name = re.sub(r"[^a-z0-9_.-]", "_", username.lower())
474
+ cache_path = effective_dir / f"github-{safe_name}.json"
475
+ try:
476
+ stats, warnings, login = fetch_stats(
477
+ username, year, token=token, max_commits=max_commits,
478
+ include_forks=include_forks, quiet=quiet,
479
+ cache_path=cache_path, tz=tz,
480
+ )
481
+ if (
482
+ fallback_previous
483
+ and not stats.commit_count
484
+ and year == datetime.now().year
485
+ ):
486
+ previous, prev_warnings, login = fetch_stats(
487
+ username, year - 1, token=token, max_commits=max_commits,
488
+ include_forks=include_forks, quiet=quiet,
489
+ cache_path=cache_path, tz=tz,
490
+ )
491
+ if previous.commit_count:
492
+ stats, warnings = previous, prev_warnings
493
+ except RuntimeError as exc:
494
+ print(str(exc), file=sys.stderr)
495
+ return 1
496
+
497
+ year = stats.year
498
+ out = Path(out_dir)
499
+ formats = {"card"} if card_only else None
500
+ written = render(stats, out, formats=formats, card_theme=theme)
501
+ embed = chr(10).join([
502
+ "<picture>",
503
+ f' <source media="(prefers-color-scheme: dark)" '
504
+ f'srcset="./codeyear-{year}-card-dark.svg">',
505
+ f' <img src="./codeyear-{year}-card.svg" width="640" '
506
+ f'alt="CodeYear {year}">',
507
+ "</picture>",
508
+ "",
509
+ ])
510
+ embed_path = out / f"codeyear-{year}-embed.md"
511
+ embed_path.write_text(embed, encoding="utf-8")
512
+ written.append(("EMBED", embed_path))
513
+ embed_en = chr(10).join([
514
+ "<picture>",
515
+ f' <source media="(prefers-color-scheme: dark)" '
516
+ f'srcset="./codeyear-{year}-card-en-dark.svg">',
517
+ f' <img src="./codeyear-{year}-card-en.svg" width="640" '
518
+ f'alt="CodeYear {year}">',
519
+ "</picture>",
520
+ "",
521
+ ])
522
+ embed_en_path = out / f"codeyear-{year}-embed-en.md"
523
+ embed_en_path.write_text(embed_en, encoding="utf-8")
524
+ written.append(("EMBED-EN", embed_en_path))
525
+
526
+ if profile_repo:
527
+ cards = {label: path for label, path in written}
528
+ if lang == "en":
529
+ light, dark = cards.get("CARD-EN"), cards.get("CARD-DARK-EN")
530
+ else:
531
+ light, dark = cards.get("CARD"), cards.get("CARD-DARK")
532
+ if light and dark:
533
+ from .profile import update_profile
534
+
535
+ try:
536
+ repo, changed, pushed = update_profile(
537
+ profile_repo, year, light, dark, push=push_profile,
538
+ )
539
+ written.append(("PROFILE", repo))
540
+ if changed:
541
+ state = "已提交并推送" if pushed else "仅写入本地"
542
+ print("\n" + i18n.tr(
543
+ "Profile {state} · {repo}",
544
+ state=i18n.tr(state), repo=repo,
545
+ ))
546
+ else:
547
+ print("\n" + i18n.tr(
548
+ "Profile 卡片已是最新 · {repo}", repo=repo,
549
+ ))
550
+ except Exception as exc: # pragma: no cover - user environment
551
+ print(i18n.tr(
552
+ " ! 更新 Profile 失败: {exc}", exc=exc
553
+ ), file=sys.stderr)
554
+ return 1
555
+
556
+ print()
557
+ print(i18n.tr(
558
+ "CodeYear {year} · {title}",
559
+ year=year, title=stats.persona.title,
560
+ ))
561
+ print("-" * 46)
562
+ print(f"{i18n.tr('账号'):<10}github.com/{login}")
563
+ print(f"{i18n.tr('仓库'):<10}{stats.repo_count}")
564
+ print(f"{i18n.tr('提交'):<10}{fmt_int(stats.commit_count)}")
565
+ print(f"{i18n.tr('代码行'):<10}{fmt_human(stats.lines_changed)}")
566
+ print(i18n.tr(
567
+ "活跃 {days} 天 · 涉及 {count} 个文件",
568
+ days=stats.active_days, count=stats.file_count,
569
+ ))
570
+ print(f"{i18n.tr('输出'):<10}{out.resolve()}")
571
+ print("-" * 46)
572
+ for label, path in written:
573
+ print(f"{label:<9} {path.name}")
574
+ if warnings:
575
+ print()
576
+ print(i18n.tr("提示:"))
577
+ for warning in warnings:
578
+ print(f" - {warning}")
579
+ if open_report:
580
+ html = report_path(written, lang=lang)
581
+ if html:
582
+ try:
583
+ if hasattr(os, "startfile"):
584
+ os.startfile(str(html)) # type: ignore[attr-defined]
585
+ else:
586
+ import webbrowser
587
+ webbrowser.open(html.resolve().as_uri())
588
+ except Exception:
589
+ pass
590
+ return 0