Skip to content

docs: 同步 Python 规范至 Google Python Style Guide 最新版#42

Merged
whg517 merged 2 commits intopyloong:mainfrom
whg517:worktree-update-python-standards
Apr 28, 2026
Merged

docs: 同步 Python 规范至 Google Python Style Guide 最新版#42
whg517 merged 2 commits intopyloong:mainfrom
whg517:worktree-update-python-standards

Conversation

@whg517
Copy link
Copy Markdown
Member

@whg517 whg517 commented Apr 28, 2026

Summary

  • 更新 language_rules.mdstyle_rules.md 的中文翻译,同步至 Google Python Style Guide 最新版
  • 基于 pyguide.md 原文逐节对比,修正翻译与原文的遗漏和不一致

language_rules.md

  • §1.1: viking_cafe_order 添加类型标注 (str | None, -> str)
  • §1.2: 保留 features 代码标识符而非误译为"功能"
  • §1.4: 异常示例添加 minimum: intif not portif port is None,更新 assert 指导
  • §1.5: 标题"全局变量" → "可变全局状态",定义更新
  • §1.11: 补充"三元运算符"定义,修正"不推荐"示例换行模式
  • §1.16: get_adderfoo 添加类型标注
  • §1.18: 修正 queue 模块名大小写
  • §1.20: 修正错别字,决策段落与上游同步
  • §1.21: List[int]list[int]

style_rules.md

  • §3.2: 添加 docstring 80 字符限制说明
  • §3.4: 更新闭合括号规则
  • §3.4.1: 添加单元素元组逗号指导
  • §3.7: PEP-394 链接改为直链
  • §3.8.2: one lineone-line,修正缩进
  • §3.8.3: 补充 Yields: 生成器说明
  • §3.8.3.1: 新增 @override 装饰器章节
  • §3.8.4: 添加 Attributes 文档记录 + property 示例
  • §3.8.5: 修正代码间距 i - 1i-1
  • §3.10: 更新字符串累积示例,补充隐式拼接示例,添加摊销线性复杂度说明
  • §3.10.2: {p!r}{p=}
  • §3.11: 修正 h5py 链接,补充"卸载文件系统"
  • §3.12: TODO 格式与上游同步(强调 bug 引用优先)
  • §3.13: 补充 collections.abc 导入例外
  • §3.16/3.16.1/3.16.5: 更新命名引言,添加数学符号命名例外和 pylint disable 示例
  • §3.16.2: 补充单元测试可访问受保护常量的说明
  • §3.17: main(argv)main(argv: Sequence[str])
  • §3.19.1: 添加 Self 类型示例
  • §3.19.10: 修正 _P.args/_P.kwargsunicodestr
  • §3.19.12: 添加 collections.abc.Sequence 优先指导,添加 tuple/cast/TYPE_CHECKING
  • 修复断链 #3106#3196

Test plan

  • MkDocs 构建通过,无错误和警告
  • 所有变更保持原有中文翻译风格
  • MkDocs admonition 语法正确 (!!! success/!!! fail)
  • 基于 Google pyguide.md 原文逐节对比验证

🤖 Generated with Claude Code

whg517 and others added 2 commits April 27, 2026 14:37
基于 Google Python Style Guide 最新版本同步翻译文档,修复以下问题:

language_rules.md:
- 移除或修正与原文不一致的内容
- 补充遗漏的关键说明(如 self/cls 限定、generator_stop 示例)
- 修复笔误和链接
- 更新代码示例以匹配原文

style_rules.md:
- 同步 @OverRide 三种使用场景
- 更新循环累加示例格式
- 补充"避免缩写"命名规则
- 移除捏造的代码示例
- 类型标注现代化(Optional[X] → X | None)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
基于 pyguide.md 原文逐节对比,修正翻译与原文的遗漏和不一致。

language_rules.md:
- §1.2: 保留 features 代码标识符而非误译为"功能"
- §1.11: 补充"三元运算符"定义,修正"不推荐"示例换行
- §1.18: 修正 queue 模块名大小写
- §1.20: 修正错别字,决策段落与上游同步

style_rules.md:
- §3.7: PEP-394 链接改为直链
- §3.8.2: one-line 连字符及缩进修正
- §3.8.3: 补充 Yields 生成器说明
- §3.10: 更新字符串累积示例,补充隐式拼接示例
- §3.11: 修正 h5py 链接,补充"卸载文件系统"
- §3.12: TODO 格式与上游同步
- §3.13: 补充 collections.abc 导入例外
- §3.16.1: 补充数学符号命名例外
- §3.16.2: 补充单元测试访问受保护常量说明
- §3.19.10: unicode → str 术语更新

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@whg517 whg517 merged commit 79093e5 into pyloong:main Apr 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant