更新《Python风格规范》

google-python-styleguide/index.rst

@@ -19,11 +19,11 @@
         `guoqiao <http://guoqiao.me/>`_ v2.19
         `xuxinkun <https://github.com/xuxinkun>`_ v2.59
         `captainfffsama <https://github.com/captainfffsama>`_ v2.6
-        `楼宇 <https://github.com/LouYu2015>`_ 2023 年 4 月 5 日更新
+        `楼宇 <https://github.com/LouYu2015>`_ 2023 年 4 月 16 日更新
 
 :项目主页:
     - `Google Style Guide (英文原版) <https://github.com/google/styleguide>`_
     - `Google 开源项目风格指南 - 中文版 <http://github.com/zh-google-styleguide/zh-google-styleguide>`_
 
 :协议:
-    Python风格指南的源代码采用Apache License 2.0协议, 文本内容采用 `CC-BY 3.0 <https://creativecommons.org/licenses/by/3.0/>`_ 协议.
+    Python风格指南的源文件采用Apache License 2.0协议, 文本内容采用 `CC-BY 3.0 <https://creativecommons.org/licenses/by/3.0/>`_ 协议.

google-python-styleguide/parting_words.rst

@@ -1,23 +1,8 @@
 临别赠言
 ================================
 
-**请务必保持代码的一致性**
+**务必保持一致性.**
 
-如果你正在编辑代码, 花几分钟看一下周边代码, 然后决定风格. 如果它们在所有的算术操作符两边都使用空格, 那么你也应该这样做. 如果它们的注释都用标记包围起来, 那么你的注释也要这样.
+编辑代码时, 请花几分钟观察一下周边代码的风格. 如果这些代码在所有运算符的周围加上了空格, 那么你也应该这样做. 如果这些代码的注释都用井号形成的框包围起来, 那么你的注释也要用井号形成的框包起来.
 
-制定风格指南的目的在于让代码有规可循, 这样人们就可以专注于"你在说什么", 而不是"你在怎么说". 我们在这里给出的是全局的规范, 但是本地的规范同样重要. 如果你加到一个文件里的代码和原有代码大相径庭, 它会让读者不知所措. 避免这种情况. 
-
-
-
-.. line-block::
-
-    Revision 2.60
-
-    Amit Patel
-    Antoine Picard
-    Eugene Jhong
-    Gregory P. Smith
-    Jeremy Hylton
-    Matt Smart
-    Mike Shields
-    Shane Liebling
+制定风格指南是为了像字典一样让代码有章可循. 这样人们可以专注于"写什么", 而不是纠结"怎么写". 我们在这里列出的全局规范就像字典, 但是局部的规范同样重要. 如果你添加的代码和周围原有的代码大相径庭, 就会打乱读者的阅读节奏. 不要这样.

google-python-styleguide/python_language_rules.rst

@@ -5,7 +5,7 @@ Lint
 --------------------
 
 .. tip::
-    用 `pylintrc <https://google.github.io/styleguide/pylintrc>`_ 运行 pylint，以检查你的代码.
+    用 `pylintrc <https://google.github.io/styleguide/pylintrc>`_ 运行 pylint, 以检查你的代码.
 
 定义:
     pylint 是在 Python 代码中寻找 bug 和格式问题的工具. 它寻找的问题就像 C 和 C++ 这些更静态的(译者注: 原文是less dynamic)语言中编译器捕捉的问题. 出于Python的动态特性, 部分警告可能有误. 不过, 误报应该不常见.
@@ -43,6 +43,7 @@ Lint
         def viking_cafe_order(spam: str, beans: str, eggs: str | None = None) -> str:
             del beans, eggs  # 未被维京人使用.
             return spam + spam + spam
+
     (译者注：Viking 意为维京人.)
 
     其他避免这种警告的常用方法还有: 用`_`作为未使用参数的名称; 给这些参数名加上前缀 ``unused_``; 或者把它们赋值给变量 ``_``. 我们允许但是不再推荐这些方法. 这会导致调用者无法通过参数名来传参，也不能保证变量确实没被引用。
@@ -497,35 +498,35 @@ Lambda函数
             ...
         
 
-特性(properties) 
+特性 (properties) 
 --------------------
 
 (译者注:参照fluent python.这里将 "property" 译为"特性",而 "attribute" 译为属性. python中数据的属性和处理数据的方法统称属性"(arrtibute)", 而在不改变类接口的前提下用来修改数据属性的存取方法我们称为"特性(property)".)
 
 .. tip::
-    可以用特性来读取、写入涉及简单计算、逻辑的属性. 特性的实现必须和属性一样满足这些通用要求: 轻量、直白、明确.
+    可以用特性来读取或设置涉及简单计算、逻辑的属性. 特性的实现必须和属性 (attribute) 一样满足这些通用要求: 轻量、直白、明确.
     
 定义:
-    把读取、写入属性的函数包装为常规属性操作的写法.
+    把读取、设置属性的函数包装为常规属性操作的写法.
     
 优点:
-    #. 可以直接实现属性的访问、赋值接口, 而不必添加访问函数 (getter) 和变异函数 (setter).
+    #. 可以直接实现属性的访问、赋值接口, 而不必添加获取器 (getter) 和设置器 (setter).
     #. 可以让属性变为只读.
     #. 可以实现惰性求值.
     #. 类的内部实现发生变化时, 可以用这种方法让用户看到的公开接口保持不变.
     
 缺点:
-    #. 可能掩盖副作用, 类似运算符重载.
+    #. 可能掩盖副作用, 类似运算符重载 (operator overload).
     #. 子类继承时可能产生困惑.
 
 结论:
-    允许使用特性, 但是, 和运算符重载一样, 只能在必要时使用, 并且要模仿常规属性的存取特点. 若无法满足要求, 请参考访问函数和变异函数的规则.
+    允许使用特性. 但是, 和运算符重载一样, 只能在必要时使用, 并且要模仿常规属性的存取特点. 若无法满足要求, 请参考 :ref:`设置器和写入器 <getter_setter>` 的规则.
     
     举个例子, 一个特性不能仅仅用于获取和设置一个内部属性: 因为不涉及计算, 没有必要用特性 (应该把该属性设为公有). 而用特性来限制属性的访问或者计算 **简单** 的衍生值则是正确的: 这种逻辑简单明了.
     
-    应该用 ``@property`` `装饰器 <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Function_and_Method_Decorators>`_ 来创建特性. 自行实现的特性装饰器属于威力过大的功能.
+    应该用 ``@property`` `装饰器 (decorator) <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Function_and_Method_Decorators>`_ 来创建特性. 自行实现的特性装饰器属于威力过大的功能.
 
-    特性的继承机制难以理解. 不要用特性实现子类能覆盖或扩展的计算功能.
+    特性的继承机制难以理解. 不要用特性实现子类能覆写 (override) 或扩展的计算功能.
     
 True/False的求值
 --------------------
@@ -581,7 +582,7 @@ True/False的求值
     #. 注意, Numpy 数组转换为布尔值时可能抛出异常. 因此建议用 `.size` 属性检查 ``np.array`` 是否为空 (例如 ``if not users.size``).
     
 词法作用域(Lexical Scoping, 又名静态作用域)
------------------------------
+---------------------------------------------
 
 .. tip::
     可以使用.
@@ -701,7 +702,7 @@ True/False的求值
 
 
 现代python: from __future__ imports
---------------------
+--------------------------------------
 
 .. tip::
     可以通过导入 ``__future__`` 包, 在较老的运行时上启用新语法, 并且只在特定文件上生效.