Python 样式指南

Fuchsia 项目遵循 Google Python 样式指南,并进行了一些优化

Google Python 样式指南允许更多变体(可能会涵盖大量现有源代码)。本指南包含的选择更严格。因此,Fuchsia Python 文件也符合 Google 样式指南,但 Google Python 文件可能不符合本指南。如需了解详情,请参阅下文的优化部分。

Python 版本

构建调用的脚本

构建调用的脚本(GN 或 Ninja)使用 Python 3.8 执行。

构建系统可确保所有 Python 脚本都由作为 Fuchsia 源代码检出的一部分安装的解释器执行。

其他脚本

直接调用的脚本应使用 Shebang 中的 python,并同时与版本 2 和版本 3 兼容:#!/usr/bin/env python

开发 Fuchsia 模块的开发者可能会使用各种平台。某些平台包含 Python 2,而不包含 Python 3,反之亦然。在 Python 3 纳入我们支持的卓越开发环境之前,我们应支持 Python 2。

虽然支持 Python 2,但请在这两个版本上测试脚本。

所有政策变更都会反映在本文档中。

多重继承

强烈建议不要使用多重继承。这与 Google C++ 样式指南:有“菱形”继承风险模式列出的原因相同,这些模式容易混淆。如果发现不合理避免多重继承的情况,则涉及的所有类最初都必须从基类 object 继承,该基类用于控制使用哪种多重继承方案。

使用 Unicode 表示文本

在支持 Python 2.x(请参阅 Python 版本)的脚本中,使用 u""unicode()unichr()b""bytes()byte() 将文本字符串显式声明为 Unicode,将二进制数据声明为字节。Python 3.x 默认使用 Unicode 处理字符串,因此在停止支持 Python 2 后,此准则将被移除。

Yes:

  a = u"Hello"  # Unicode constant.
  b = unicode(foo)  # Convert to Unicode.
  c = unichr(c)  # Convert to Unicode.
  d = io.open("bar.txt").read()  # Read text as Unicode.
No:

  a = "Hello"  # Ambiguous (depends on Python version).
  b = str(foo)  # Convert to ascii.
  c = chr(c)  # Convert to ascii.
  d = open("bar.txt").read()  # Read text as ascii.

优化条件

我们对 Google Python 样式指南进行的以下优化主要是在变体版本之间进行选择。例如,如果风格指南指出您可以执行 A、B 或 C 这 3 个任务,那么我们可能会选择支持 B 选项,而放弃其他选项。

缩进

避免与起始分隔符对齐。倾向于使用固定(4 个空格)缩进来缩进。

(有关比较,请参阅 Google Python 样式指南中的缩进。)

对账单

避免创建单行语句,即使使用 if 语句也是如此。

Yes:

    if foo:
        bar(foo)
No:

    if foo: bar(foo)

(有关比较,请参阅 Google Python 样式指南中的语句。)

类型注解

在支持 Python 2(请参阅 Python 版本)的脚本中,不会使用类型注释。

(有关比较,请参阅 Google Python 样式指南中的类型注解。)

字符串

首选字符串使用英文双引号 (")。如果使用单引号使声明更易于阅读,请使用英文单引号。例如,'The cat said "Meow"'"The cat said \\"Meow\\"" 更具可读性。

(有关比较,请参阅 Google Python 样式指南中的字符串。)

保持一致

在较大的范围内保持一致。避免在 Fuchsia 中显示一致的小口袋。仅在单个文件或目录中保持一致是不一致的。

third_party 中,目的是遵循该项目或库的现有样式。在该库中查找适当的样式指南。

(请参阅 Google Python 样式指南中的分词。)