codeyear 0.2.14__tar.gz → 0.2.16__tar.gz

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.
Files changed (42) hide show
  1. {codeyear-0.2.14 → codeyear-0.2.16}/PKG-INFO +22 -11
  2. {codeyear-0.2.14 → codeyear-0.2.16}/README.md +20 -10
  3. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/__init__.py +1 -1
  4. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/card.py +13 -15
  5. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/cli.py +55 -88
  6. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/config.py +5 -0
  7. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/github_public.py +154 -34
  8. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/gui.py +57 -11
  9. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/html_report.py +57 -32
  10. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/i18n.py +23 -1
  11. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/poster.py +13 -15
  12. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/profile.py +69 -15
  13. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/report_theme.py +8 -0
  14. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/runner.py +14 -0
  15. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/scanner.py +32 -32
  16. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/server.py +88 -11
  17. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/stats.py +80 -14
  18. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/updater.py +83 -23
  19. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear.egg-info/PKG-INFO +22 -11
  20. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear.egg-info/SOURCES.txt +10 -1
  21. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear.egg-info/requires.txt +1 -0
  22. {codeyear-0.2.14 → codeyear-0.2.16}/pyproject.toml +2 -2
  23. codeyear-0.2.16/tests/test_cli_boolean_overrides.py +52 -0
  24. codeyear-0.2.16/tests/test_commit_completeness.py +86 -0
  25. codeyear-0.2.16/tests/test_github_fallback.py +65 -0
  26. codeyear-0.2.16/tests/test_github_pagination_completeness.py +24 -0
  27. codeyear-0.2.16/tests/test_profile_push_safety.py +174 -0
  28. codeyear-0.2.16/tests/test_public_push_safety.py +34 -0
  29. codeyear-0.2.16/tests/test_review_regressions.py +446 -0
  30. codeyear-0.2.16/tests/test_updater_prerelease.py +20 -0
  31. codeyear-0.2.16/tests/test_updater_versions.py +16 -0
  32. {codeyear-0.2.14 → codeyear-0.2.16}/LICENSE +0 -0
  33. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/__main__.py +0 -0
  34. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/keywords.py +0 -0
  35. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/languages.py +0 -0
  36. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/personas.py +0 -0
  37. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear/wizard.py +0 -0
  38. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear.egg-info/dependency_links.txt +0 -0
  39. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear.egg-info/entry_points.txt +0 -0
  40. {codeyear-0.2.14 → codeyear-0.2.16}/codeyear.egg-info/top_level.txt +0 -0
  41. {codeyear-0.2.14 → codeyear-0.2.16}/setup.cfg +0 -0
  42. {codeyear-0.2.14 → codeyear-0.2.16}/tests/test_core.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codeyear
3
- Version: 0.2.14
3
+ Version: 0.2.16
4
4
  Summary: Local-first annual coding report generated from your own git history.
5
5
  Author: CodeYear contributors
6
6
  License: MIT
@@ -24,6 +24,7 @@ Requires-Python: >=3.9
24
24
  Description-Content-Type: text/markdown
25
25
  License-File: LICENSE
26
26
  Requires-Dist: Pillow>=9.0
27
+ Requires-Dist: packaging>=23.0
27
28
  Provides-Extra: dev
28
29
  Requires-Dist: pytest>=8; extra == "dev"
29
30
  Requires-Dist: pytest-cov>=5; extra == "dev"
@@ -40,8 +41,8 @@ Dynamic: license-file
40
41
  **简体中文** | [English](README.en.md) · [中文简介](docs/intro.zh.md)
41
42
 
42
43
  > 扫描你本地的 git 仓库,生成一份**只属于你**的年度代码手账:中英双语 HTML 报告、
43
- > 2400×3200 海报、完整长图,以及 GitHub 主页卡片。默认只读本地 git,不登录、不上传;
44
- > 公开 GitHub 模式是可选联网功能。
44
+ > 2400×3200 海报、完整长图,以及 GitHub 主页卡片。CLI 本地扫描默认不联网、不上传;
45
+ > GUI 默认会联网检查更新,公开 GitHub 模式和推送是可选联网功能。
45
46
 
46
47
  ![CodeYear 报告预览](docs/report-preview.png)
47
48
 
@@ -65,7 +66,7 @@ codeyear
65
66
  也可以从 Release 下载 wheel:
66
67
 
67
68
  ```bash
68
- pip install https://github.com/Qiongkura/codeyear/releases/download/v0.2.14/codeyear-0.2.14-py3-none-any.whl
69
+ pip install https://github.com/Qiongkura/codeyear/releases/download/v0.2.16/codeyear-0.2.16-py3-none-any.whl
69
70
  ```
70
71
 
71
72
  > exe 未做代码签名,Windows SmartScreen 可能提示;点「更多信息 → 仍要运行」。
@@ -85,7 +86,7 @@ python -m codeyear scan ~/code --open
85
86
  或者用 uv 一行免安装运行(需要先装 [uv](https://docs.astral.sh/uv/)):
86
87
 
87
88
  ```bash
88
- uvx --from "https://github.com/Qiongkura/codeyear/releases/download/v0.2.14/codeyear-0.2.14-py3-none-any.whl" codeyear scan ~/code --open
89
+ uvx --from "https://github.com/Qiongkura/codeyear/releases/download/v0.2.16/codeyear-0.2.16-py3-none-any.whl" codeyear scan ~/code --open
89
90
  # 或直接从源码运行:
90
91
  uvx --from git+https://github.com/Qiongkura/codeyear.git codeyear scan ~/code --open
91
92
  ```
@@ -112,7 +113,8 @@ codeyear
112
113
  ```
113
114
 
114
115
  会打开桌面窗口:添加多个目录、检查仓库数量、看进度条、选输出位置,完成后直接打开报告。
115
- Windows 也可以在仓库根目录双击 `CodeYear.cmd`。
116
+ Windows 也可以在仓库根目录双击 `CodeYear.cmd`。GUI 默认启动时联网检查版本更新;
117
+ 设置环境变量 `CODEYEAR_NO_UPDATE_CHECK=1` 可关闭自动检查(手动检查仍可联网)。
116
118
 
117
119
  需要 Tkinter;Windows/macOS 的 Python 自带,Linux 装 `python3-tk`。安装后也可以运行 `codeyear-gui`。
118
120
 
@@ -216,7 +218,7 @@ https://your-host/card.svg?username=Qiongkura&year=2026&lang=en
216
218
  > 文件名绕过 GitHub 的图片缓存;无需手动粘贴 embed 片段。模板默认每天 04:00 UTC
217
219
  > 更新;改 workflow 里的 `cron` 可切成每周一 `0 4 * * 1` 或每月 1 日 `0 4 1 * *`。
218
220
  > 跨年时如果新的一年还没有提交,`--fallback-previous` 会继续显示上一年的卡片。
219
- > 模板直接安装 Release 里的 wheel;升级时改 `CODEYEAR_VERSION`(当前 `0.2.14`)。
221
+ > 模板直接安装 Release 里的 wheel;升级时改 `CODEYEAR_VERSION`(当前 `0.2.16`)。
220
222
  > 提交量大的账号建议在 Profile 仓库添加 `CODEYEAR_TOKEN`(PAT)secret;模板会优先使用它,
221
223
  > 否则回退到 `GITHUB_TOKEN`。`GITHUB_TOKEN` 在 Actions 里通常只有 1,000 次/小时额度,
222
224
  > 超过这个量时提交详情会被截断。
@@ -286,7 +288,7 @@ CodeYear 是给开发者做的「年度报告」。官方的 Wrapped 通常只
286
288
 
287
289
  ## 安装与输出
288
290
 
289
- 上面的命令只会安装 Pillow。想把 CodeYear 安装成全局命令:
291
+ 上面的命令会安装 Pillow 和版本比较所需的 packaging。想把 CodeYear 安装成全局命令:
290
292
 
291
293
  ```bash
292
294
  pip install -e .
@@ -365,6 +367,12 @@ codeyear github Qiongkura --year 2026 --card-only \
365
367
  `codeyear-2026-card-vN.svg` 并重写 README,同时清掉旧版本文件;跨年时也会把 README
366
368
  里上一年的引用替换成新一年的卡片。
367
369
 
370
+ 推送前会联网核对当前分支对应的远端上游分支:本地 HEAD 必须与远端完全一致,
371
+ 否则拒绝修改 Profile 或提交,避免把已有未推送提交一起发出去;没有上游、远端分支
372
+ 无法验证、存在已暂存修改或 README/卡片已有未提交修改时也会拒绝。请先自行处理并
373
+ 同步提交,再重试。推送只指定该上游分支,远端并发更新可能导致推送失败,需手动同步。
374
+ 源码版公开数据获取出现不完整警告时,`--push-profile` 也会取消,需先处理警告。
375
+
368
376
  私有仓库要定时更新,可以用 Windows 任务计划、cron 或 self-hosted runner:
369
377
  [定时更新私有项目卡片](docs/schedule.md)。
370
378
 
@@ -449,12 +457,15 @@ codeyear scan D:\code --year 2026 --compare
449
457
  支持 `roots / year / out / author / all_authors / aliases / compare /
450
458
  fallback_previous / all_branches / no_mailmap / jobs / max_depth / timeout /
451
459
  theme / max_commits / open`。命令行显式参数优先于配置文件;文件不存在或字段
452
- 类型不对时会自动忽略。
460
+ 类型不对时会自动忽略。布尔参数可用反向开关临时覆盖,例如 `--no-compare`、
461
+ `--no-rolling`、`--no-open`;使用 `--mailmap` 可覆盖配置中的 `no_mailmap`。
462
+ 公开模式的 `--require-complete` 会在数据警告时退出,可用于单独提交卡片的自动化脚本。
453
463
 
454
464
  ## 隐私
455
465
 
456
- - 默认 `scan` 模式所有统计都在本地完成,**没有任何网络请求**。
457
- - `github` 公开模式、`serve` 在线服务和 `--push-profile` 是可选联网功能;它们只读取公开 GitHub 数据或推送卡片,不会上传本地代码。
466
+ - CLI `scan` 默认只在本地统计,不发网络请求;显式启用 `--push-profile` 例外。
467
+ - GUI 默认联网检查更新;设置 `CODEYEAR_NO_UPDATE_CHECK=1` 可禁用自动检查。
468
+ - `github` 公开模式、`serve` 在线服务和 `--push-profile` 是可选联网功能;推送会发送卡片和 Profile README,以及这些内容包含的数据。
458
469
  - 本地模式只读 `git log`、`git tag`、仓库根目录 README 的第一行和 `git remote`;不读取其它工作区文件。
459
470
  - 输出文件默认忽略在 `.gitignore` 里。
460
471
  - 本地报告页脚标注 `LOCAL ONLY · 数据未上传`;公开模式报告会标注公开数据来源。
@@ -8,8 +8,8 @@
8
8
  **简体中文** | [English](README.en.md) · [中文简介](docs/intro.zh.md)
9
9
 
10
10
  > 扫描你本地的 git 仓库,生成一份**只属于你**的年度代码手账:中英双语 HTML 报告、
11
- > 2400×3200 海报、完整长图,以及 GitHub 主页卡片。默认只读本地 git,不登录、不上传;
12
- > 公开 GitHub 模式是可选联网功能。
11
+ > 2400×3200 海报、完整长图,以及 GitHub 主页卡片。CLI 本地扫描默认不联网、不上传;
12
+ > GUI 默认会联网检查更新,公开 GitHub 模式和推送是可选联网功能。
13
13
 
14
14
  ![CodeYear 报告预览](docs/report-preview.png)
15
15
 
@@ -33,7 +33,7 @@ codeyear
33
33
  也可以从 Release 下载 wheel:
34
34
 
35
35
  ```bash
36
- pip install https://github.com/Qiongkura/codeyear/releases/download/v0.2.14/codeyear-0.2.14-py3-none-any.whl
36
+ pip install https://github.com/Qiongkura/codeyear/releases/download/v0.2.16/codeyear-0.2.16-py3-none-any.whl
37
37
  ```
38
38
 
39
39
  > exe 未做代码签名,Windows SmartScreen 可能提示;点「更多信息 → 仍要运行」。
@@ -53,7 +53,7 @@ python -m codeyear scan ~/code --open
53
53
  或者用 uv 一行免安装运行(需要先装 [uv](https://docs.astral.sh/uv/)):
54
54
 
55
55
  ```bash
56
- uvx --from "https://github.com/Qiongkura/codeyear/releases/download/v0.2.14/codeyear-0.2.14-py3-none-any.whl" codeyear scan ~/code --open
56
+ uvx --from "https://github.com/Qiongkura/codeyear/releases/download/v0.2.16/codeyear-0.2.16-py3-none-any.whl" codeyear scan ~/code --open
57
57
  # 或直接从源码运行:
58
58
  uvx --from git+https://github.com/Qiongkura/codeyear.git codeyear scan ~/code --open
59
59
  ```
@@ -80,7 +80,8 @@ codeyear
80
80
  ```
81
81
 
82
82
  会打开桌面窗口:添加多个目录、检查仓库数量、看进度条、选输出位置,完成后直接打开报告。
83
- Windows 也可以在仓库根目录双击 `CodeYear.cmd`。
83
+ Windows 也可以在仓库根目录双击 `CodeYear.cmd`。GUI 默认启动时联网检查版本更新;
84
+ 设置环境变量 `CODEYEAR_NO_UPDATE_CHECK=1` 可关闭自动检查(手动检查仍可联网)。
84
85
 
85
86
  需要 Tkinter;Windows/macOS 的 Python 自带,Linux 装 `python3-tk`。安装后也可以运行 `codeyear-gui`。
86
87
 
@@ -184,7 +185,7 @@ https://your-host/card.svg?username=Qiongkura&year=2026&lang=en
184
185
  > 文件名绕过 GitHub 的图片缓存;无需手动粘贴 embed 片段。模板默认每天 04:00 UTC
185
186
  > 更新;改 workflow 里的 `cron` 可切成每周一 `0 4 * * 1` 或每月 1 日 `0 4 1 * *`。
186
187
  > 跨年时如果新的一年还没有提交,`--fallback-previous` 会继续显示上一年的卡片。
187
- > 模板直接安装 Release 里的 wheel;升级时改 `CODEYEAR_VERSION`(当前 `0.2.14`)。
188
+ > 模板直接安装 Release 里的 wheel;升级时改 `CODEYEAR_VERSION`(当前 `0.2.16`)。
188
189
  > 提交量大的账号建议在 Profile 仓库添加 `CODEYEAR_TOKEN`(PAT)secret;模板会优先使用它,
189
190
  > 否则回退到 `GITHUB_TOKEN`。`GITHUB_TOKEN` 在 Actions 里通常只有 1,000 次/小时额度,
190
191
  > 超过这个量时提交详情会被截断。
@@ -254,7 +255,7 @@ CodeYear 是给开发者做的「年度报告」。官方的 Wrapped 通常只
254
255
 
255
256
  ## 安装与输出
256
257
 
257
- 上面的命令只会安装 Pillow。想把 CodeYear 安装成全局命令:
258
+ 上面的命令会安装 Pillow 和版本比较所需的 packaging。想把 CodeYear 安装成全局命令:
258
259
 
259
260
  ```bash
260
261
  pip install -e .
@@ -333,6 +334,12 @@ codeyear github Qiongkura --year 2026 --card-only \
333
334
  `codeyear-2026-card-vN.svg` 并重写 README,同时清掉旧版本文件;跨年时也会把 README
334
335
  里上一年的引用替换成新一年的卡片。
335
336
 
337
+ 推送前会联网核对当前分支对应的远端上游分支:本地 HEAD 必须与远端完全一致,
338
+ 否则拒绝修改 Profile 或提交,避免把已有未推送提交一起发出去;没有上游、远端分支
339
+ 无法验证、存在已暂存修改或 README/卡片已有未提交修改时也会拒绝。请先自行处理并
340
+ 同步提交,再重试。推送只指定该上游分支,远端并发更新可能导致推送失败,需手动同步。
341
+ 源码版公开数据获取出现不完整警告时,`--push-profile` 也会取消,需先处理警告。
342
+
336
343
  私有仓库要定时更新,可以用 Windows 任务计划、cron 或 self-hosted runner:
337
344
  [定时更新私有项目卡片](docs/schedule.md)。
338
345
 
@@ -417,12 +424,15 @@ codeyear scan D:\code --year 2026 --compare
417
424
  支持 `roots / year / out / author / all_authors / aliases / compare /
418
425
  fallback_previous / all_branches / no_mailmap / jobs / max_depth / timeout /
419
426
  theme / max_commits / open`。命令行显式参数优先于配置文件;文件不存在或字段
420
- 类型不对时会自动忽略。
427
+ 类型不对时会自动忽略。布尔参数可用反向开关临时覆盖,例如 `--no-compare`、
428
+ `--no-rolling`、`--no-open`;使用 `--mailmap` 可覆盖配置中的 `no_mailmap`。
429
+ 公开模式的 `--require-complete` 会在数据警告时退出,可用于单独提交卡片的自动化脚本。
421
430
 
422
431
  ## 隐私
423
432
 
424
- - 默认 `scan` 模式所有统计都在本地完成,**没有任何网络请求**。
425
- - `github` 公开模式、`serve` 在线服务和 `--push-profile` 是可选联网功能;它们只读取公开 GitHub 数据或推送卡片,不会上传本地代码。
433
+ - CLI `scan` 默认只在本地统计,不发网络请求;显式启用 `--push-profile` 例外。
434
+ - GUI 默认联网检查更新;设置 `CODEYEAR_NO_UPDATE_CHECK=1` 可禁用自动检查。
435
+ - `github` 公开模式、`serve` 在线服务和 `--push-profile` 是可选联网功能;推送会发送卡片和 Profile README,以及这些内容包含的数据。
426
436
  - 本地模式只读 `git log`、`git tag`、仓库根目录 README 的第一行和 `git remote`;不读取其它工作区文件。
427
437
  - 输出文件默认忽略在 `.gitignore` 里。
428
438
  - 本地报告页脚标注 `LOCAL ONLY · 数据未上传`;公开模式报告会标注公开数据来源。
@@ -1,3 +1,3 @@
1
1
  """CodeYear · 本地优先的年度代码报告生成器."""
2
2
 
3
- __version__ = "0.2.14"
3
+ __version__ = "0.2.16"
@@ -3,7 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import html
6
- from datetime import date, datetime, timedelta
6
+ from datetime import datetime, timedelta
7
7
  from pathlib import Path
8
8
 
9
9
  from .stats import (
@@ -14,6 +14,8 @@ from .stats import (
14
14
  fmt_signed_pair,
15
15
  language_breakdown,
16
16
  parse_daily,
17
+ window_days,
18
+ window_months,
17
19
  )
18
20
 
19
21
  W, H = 640, 1254
@@ -247,9 +249,10 @@ MONTHS = [
247
249
 
248
250
 
249
251
  def build_svg(stats: ReportStats, *, dark: bool = False,
250
- theme: str = "paper", lang: str = "zh") -> str:
252
+ theme: str = "paper", lang: str = "zh",
253
+ palette_override: dict | None = None) -> str:
251
254
  light, dark_theme = THEMES.get(theme, THEMES["paper"])
252
- c = dark_theme if dark else light
255
+ c = palette_override if palette_override is not None else (dark_theme if dark else light)
253
256
  en = lang == "en"
254
257
 
255
258
  def t(zh: str, english: str) -> str:
@@ -300,7 +303,7 @@ def build_svg(stats: ReportStats, *, dark: bool = False,
300
303
  header.append(_rule(142, c["line"]))
301
304
 
302
305
  # ---- six summary tiles (3 x 2) ------------------------------------
303
- active_pct = stats.active_days / (366 if _is_leap(stats.year) else 365)
306
+ active_pct = stats.active_days / window_days(stats)
304
307
  tiles = [
305
308
  (t("COMMITS / 提交", "COMMITS"), fmt_int(stats.commit_count),
306
309
  t("年度提交", "commits this year")),
@@ -343,19 +346,18 @@ def build_svg(stats: ReportStats, *, dark: bool = False,
343
346
 
344
347
  # ---- contribution calendar ---------------------------------------
345
348
  cell, gap_h = 9, 2
346
- grid_start = date(stats.year, 1, 1)
347
- grid_start -= timedelta(days=grid_start.weekday())
348
- grid_end = date(stats.year, 12, 31)
349
- grid_end += timedelta(days=6 - grid_end.weekday())
349
+ start_w, end_w = date_window(stats)
350
+ grid_start = start_w - timedelta(days=start_w.weekday())
351
+ grid_end = end_w + timedelta(days=6 - end_w.weekday())
350
352
  grid_cols = (grid_end - grid_start).days // 7 + 1
351
353
  grid_w = grid_cols * (cell + gap_h) - gap_h
352
354
  grid_x = (W - grid_w) / 2
353
355
 
354
356
  month_ticks = []
355
- for month in range(1, 13):
356
- col = (date(stats.year, month, 1) - grid_start).days // 7
357
+ for m_date, m_label in window_months(stats):
358
+ col = (m_date - grid_start).days // 7
357
359
  mx = grid_x + col * (cell + gap_h)
358
- month_ticks.append(_text(mx, 588, f"{month:02d}", 9.5, c["muted"]))
360
+ month_ticks.append(_text(mx, 588, m_label, 9.5, c["muted"]))
359
361
 
360
362
  charts = [
361
363
  _text(M, 350, "MONTHLY RHYTHM", 10, c["muted"], spacing=1),
@@ -702,10 +704,6 @@ def build_svg(stats: ReportStats, *, dark: bool = False,
702
704
  """
703
705
 
704
706
 
705
- def _is_leap(year: int) -> bool:
706
- return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
707
-
708
-
709
707
  def render(stats: ReportStats, out_path: str | Path, *,
710
708
  theme: str = "paper", lang: str = "zh") -> list[Path]:
711
709
  path = Path(out_path)
@@ -3,9 +3,7 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import argparse
6
- import json
7
6
  import os
8
- import subprocess
9
7
  import sys
10
8
  import webbrowser
11
9
  from datetime import date
@@ -13,17 +11,25 @@ from pathlib import Path
13
11
 
14
12
  from . import __version__, i18n
15
13
  from .card import THEMES
16
- from .card import render as render_card
17
14
  from .config import load as load_config
18
- from .html_report import render as render_html
19
- from .html_report import render_en as render_html_en
20
- from .poster import render as render_poster
21
- from .poster import render_long
22
- from .runner import discover, report_path, scan
23
- from .stats import fmt_int
15
+ from .runner import detect_identity, discover, render, report_path, scan
16
+ from .stats import fmt_int, window_days
24
17
  from .updater import check_update, cleanup_old_executable, perform_update
25
18
 
26
- _NO_WINDOW = subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0
19
+
20
+ class _CopyAppendAction(argparse.Action):
21
+ """Append action that never mutates a config-provided default list."""
22
+
23
+ def __call__(self, parser, namespace, values, option_string=None):
24
+ items = list(getattr(namespace, self.dest, None) or [])
25
+ if getattr(namespace, f"_cy_copied_{self.dest}", False) is False:
26
+ items = [] if values == "" else list(items)
27
+ setattr(namespace, f"_cy_copied_{self.dest}", True)
28
+ if values == "":
29
+ items = []
30
+ else:
31
+ items.append(values)
32
+ setattr(namespace, self.dest, items)
27
33
 
28
34
 
29
35
  def _build_parser() -> argparse.ArgumentParser:
@@ -52,12 +58,14 @@ def _build_parser() -> argparse.ArgumentParser:
52
58
  github.add_argument("--max-commits", type=int, default=cfg.get("max_commits", 200),
53
59
  help="最多拉取多少条提交(无 token 时自动限制为 30)")
54
60
  github.add_argument("--include-forks", action="store_true", help="包含 fork 仓库")
55
- github.add_argument("--open", action="store_true", default=cfg.get("open", False),
56
- help="生成后打开报告")
61
+ github.add_argument("--open", action=argparse.BooleanOptionalAction,
62
+ default=cfg.get("open", False), help="生成后打开报告")
57
63
  github.add_argument("--quiet", action="store_true", help="不打印扫描进度")
58
64
  github.add_argument("--theme", choices=sorted(THEMES),
59
65
  default=cfg.get("theme", "paper"),
60
66
  help="卡片主题:paper / mono / forest / ocean")
67
+ github.add_argument("--require-complete", action="store_true",
68
+ help="公开统计有警告时退出,避免自动更新不完整的卡片")
61
69
  github.add_argument("--card-only", action="store_true",
62
70
  help="只生成主页卡片和 embed 片段,不生成完整报告")
63
71
  github.add_argument("--profile-repo", default=None,
@@ -83,30 +91,32 @@ def _build_parser() -> argparse.ArgumentParser:
83
91
  help="要扫描的文件夹(可以多个,默认当前目录)")
84
92
  scan.add_argument("--year", type=int, default=cfg.get("year", date.today().year),
85
93
  help="统计年份,默认今年")
86
- scan.add_argument("--rolling", action="store_true",
94
+ scan.add_argument("--rolling", action=argparse.BooleanOptionalAction,
87
95
  default=cfg.get("rolling", False),
88
96
  help="统计过去 365 天(滚动年度),而非自然年")
89
- scan.add_argument("--exclude", action="append", default=cfg.get("exclude", []),
97
+ scan.add_argument("--exclude", action=_CopyAppendAction, default=list(cfg.get("exclude", [])),
90
98
  help="排除指定仓库名或通配符(可重复或逗号分隔)")
91
99
  scan.add_argument("--out", default=cfg.get("out", "codeyear-output"),
92
100
  help="输出目录,默认 ./codeyear-output")
93
101
  scan.add_argument("--author", default=cfg.get("author"),
94
102
  help="只统计匹配的 git author(--author 参数)")
95
- scan.add_argument("--compare", action="store_true",
103
+ scan.add_argument("--compare", action=argparse.BooleanOptionalAction,
96
104
  default=cfg.get("compare", False),
97
105
  help="同时扫描去年,在报告里生成同比数据")
98
- scan.add_argument("--fallback-previous", action="store_true",
106
+ scan.add_argument("--fallback-previous", action=argparse.BooleanOptionalAction,
99
107
  default=cfg.get("fallback_previous", False),
100
108
  help="当年没有提交时回退到上一年,适合跨年自动更新")
101
- scan.add_argument("--alias", action="append", default=cfg.get("aliases", []),
109
+ scan.add_argument("--alias", action=_CopyAppendAction, default=list(cfg.get("aliases", [])),
102
110
  help="额外作者邮箱或名字,可重复;用于旧提交")
103
111
  scan.add_argument("--no-mailmap", action="store_true",
104
112
  default=cfg.get("no_mailmap", False),
105
113
  help="忽略仓库里的 .mailmap(默认自动使用)")
106
- scan.add_argument("--all-branches", action="store_true",
114
+ scan.add_argument("--mailmap", dest="no_mailmap", action="store_false",
115
+ help="使用仓库里的 .mailmap")
116
+ scan.add_argument("--all-branches", action=argparse.BooleanOptionalAction,
107
117
  default=cfg.get("all_branches", False),
108
118
  help="统计所有本地分支/tag 的提交(默认只看当前分支)")
109
- scan.add_argument("--all-authors", action="store_true",
119
+ scan.add_argument("--all-authors", action=argparse.BooleanOptionalAction,
110
120
  default=cfg.get("all_authors", False),
111
121
  help="统计所有作者的提交(默认只统计你本人,按 git user.name / user.email 识别)")
112
122
  scan.add_argument("--max-depth", type=int, default=cfg.get("max_depth", 6),
@@ -126,7 +136,7 @@ def _build_parser() -> argparse.ArgumentParser:
126
136
  help="本地 GitHub Profile 仓库路径;只写入本地,不联网")
127
137
  scan.add_argument("--push-profile", action="store_true",
128
138
  help="更新后提交并推送 Profile 仓库(联网);需同时指定 --profile-repo")
129
- scan.add_argument("--open", action="store_true", default=cfg.get("open", False),
139
+ scan.add_argument("--open", action=argparse.BooleanOptionalAction, default=cfg.get("open", False),
130
140
  help="生成后自动打开报告")
131
141
  scan.add_argument("--quiet", action="store_true", help="不打印扫描进度")
132
142
  i18n.localize_parser(parser)
@@ -147,22 +157,7 @@ def _open_path(path: Path) -> None:
147
157
 
148
158
  def _detect_identity() -> tuple[str, str] | None:
149
159
  """The runner's git identity, used to keep only their own commits."""
150
-
151
- def config(key: str) -> str:
152
- try:
153
- proc = subprocess.run(
154
- ["git", "config", "--global", key],
155
- capture_output=True, text=True, encoding="utf-8",
156
- errors="replace", timeout=10, creationflags=_NO_WINDOW,
157
- )
158
- except (OSError, subprocess.TimeoutExpired):
159
- return ""
160
- return (proc.stdout or "").strip()
161
-
162
- email, name = config("user.email"), config("user.name")
163
- if email or name:
164
- return (email, name)
165
- return None
160
+ return detect_identity()
166
161
 
167
162
 
168
163
  def main(argv: list[str] | None = None) -> int:
@@ -224,7 +219,7 @@ def main(argv: list[str] | None = None) -> int:
224
219
  cache_dir=args.cache_dir,
225
220
  no_cache=args.no_cache,
226
221
  lang=i18n.get_lang(),
227
- tz=args.tz,
222
+ tz=args.tz, require_complete=args.require_complete,
228
223
  )
229
224
  if args.command == "serve":
230
225
  from .server import serve
@@ -292,6 +287,7 @@ def main(argv: list[str] | None = None) -> int:
292
287
  jobs=max(1, args.jobs), progress=progress,
293
288
  compare=args.compare, use_mailmap=not args.no_mailmap,
294
289
  all_branches=args.all_branches,
290
+ rolling=args.rolling,
295
291
  )
296
292
  if previous.commit_count:
297
293
  stats, warnings = previous, prev_warnings
@@ -308,56 +304,31 @@ def main(argv: list[str] | None = None) -> int:
308
304
  return 3
309
305
 
310
306
  out_dir = Path(args.out)
311
- out_dir.mkdir(parents=True, exist_ok=True)
312
- base = out_dir / f"codeyear-{args.year}"
313
-
314
- written: list[tuple[str, Path]] = []
315
-
316
- json_path = base.with_suffix(".json")
317
- json_path.write_text(
318
- json.dumps(stats.as_dict(), ensure_ascii=False, indent=2),
319
- encoding="utf-8",
320
- )
321
- written.append(("JSON", json_path))
322
-
307
+ formats = {"json"}
323
308
  if not args.no_html:
324
- html_path = render_html(stats, base.with_suffix(".html"))
325
- written.append(("HTML", html_path))
326
- en_path = render_html_en(stats, out_dir / f"codeyear-{args.year}-en.html")
327
- written.append(("HTML-EN", en_path))
328
-
309
+ formats.add("html")
329
310
  if not args.no_png:
330
- png_path = render_poster(stats, base.with_suffix(".png"))
331
- written.append(("PNG", png_path))
332
- if i18n.get_lang() == "en":
333
- png_en = render_poster(
334
- stats, out_dir / f"codeyear-{args.year}-en.png", lang="en")
335
- written.append(("PNG-EN", png_en))
311
+ formats.add("png")
336
312
  if not args.no_long:
337
- long_path = render_long(stats, out_dir / f"codeyear-{args.year}-long.png")
338
- written.append(("LONG", long_path))
339
- if i18n.get_lang() == "en":
340
- long_en = render_long(
341
- stats, out_dir / f"codeyear-{args.year}-en-long.png",
342
- lang="en")
343
- written.append(("LONG-EN", long_en))
344
-
345
- card_paths = []
346
- en_cards = []
347
- card_theme = getattr(args, "theme", "paper") or "paper"
313
+ formats.add("long")
348
314
  if not args.no_card:
349
- card_paths = render_card(
350
- stats, out_dir / f"codeyear-{args.year}-card.svg",
351
- theme=card_theme,
352
- )
353
- written.append(("CARD", card_paths[0]))
354
- written.append(("CARD-DARK", card_paths[1]))
355
- en_cards = render_card(
356
- stats, out_dir / f"codeyear-{args.year}-card-en.svg",
357
- theme=card_theme, lang="en",
358
- )
359
- written.append(("CARD-EN", en_cards[0]))
360
- written.append(("CARD-DARK-EN", en_cards[1]))
315
+ formats.add("card")
316
+ card_theme = getattr(args, "theme", "paper") or "paper"
317
+ written = render(
318
+ stats, out_dir, formats=formats,
319
+ card_theme=card_theme, lang=i18n.get_lang(),
320
+ )
321
+ by_label = dict(written)
322
+ card_paths = (
323
+ [by_label["CARD"], by_label["CARD-DARK"]]
324
+ if "CARD" in by_label and "CARD-DARK" in by_label
325
+ else []
326
+ )
327
+ en_cards = (
328
+ [by_label["CARD-EN"], by_label["CARD-DARK-EN"]]
329
+ if "CARD-EN" in by_label and "CARD-DARK-EN" in by_label
330
+ else []
331
+ )
361
332
 
362
333
  exit_code = 0
363
334
  if args.profile_repo:
@@ -394,7 +365,7 @@ def main(argv: list[str] | None = None) -> int:
394
365
  exit_code = 1
395
366
 
396
367
  # Console summary
397
- active_pct = stats.active_days / (366 if _is_leap(args.year) else 365)
368
+ active_pct = stats.active_days / window_days(stats)
398
369
  print()
399
370
  print(i18n.tr(
400
371
  "CodeYear {year} · {title}",
@@ -442,9 +413,5 @@ def main(argv: list[str] | None = None) -> int:
442
413
  return exit_code
443
414
 
444
415
 
445
- def _is_leap(year: int) -> bool:
446
- return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
447
-
448
-
449
416
  if __name__ == "__main__": # pragma: no cover
450
417
  raise SystemExit(main())
@@ -36,6 +36,7 @@ SCHEMA = {
36
36
  "github_user": str,
37
37
  "profile_repo": str,
38
38
  "push_profile": bool,
39
+ "lang": str,
39
40
  }
40
41
 
41
42
 
@@ -76,6 +77,8 @@ def load() -> dict:
76
77
  "paper", "mono", "forest", "ocean",
77
78
  }:
78
79
  continue
80
+ if key == "lang" and value not in {"zh", "en"}:
81
+ continue
79
82
  clean[key] = value
80
83
  if clean.get("max_commits", 1) <= 0:
81
84
  clean.pop("max_commits", None)
@@ -105,6 +108,8 @@ def save(values: dict) -> Path:
105
108
  elif expected is str and isinstance(value, str):
106
109
  if key == "theme" and value not in {"paper", "mono", "forest", "ocean"}:
107
110
  continue
111
+ if key == "lang" and value not in {"zh", "en"}:
112
+ continue
108
113
  clean[key] = value
109
114
  target = path()
110
115
  target.parent.mkdir(parents=True, exist_ok=True)