Google Python 风格指南

1 背景

在 Google , Python 是主要使用的动态语言之一。该风格之南表述了一些在 Python 编程中 应该做不应该 的事情。

为了帮你正确地格式化代码,我们准备了 Vim 的配置文件
对于 Emacs ,使用默认的应该没什么问题。

很多个团队在使用 yapf 来自动格式化来避免在格式上的争论。

2 Python 语言规范

2.1 Lint

在你的代码上运行 pylint

2.1.1 定义

pylint 是一个可以在 Python 源代码中发现 Bugs 和风格问题的工具。它可以发现一些通常由编译器捕获的问题,像 C 和 c++ 等
动态程度较低的语言。由于Python的动态特性,一些警告可能是不正确的;然而,虚假得警告应该相当少见。

2.1.2 Pros

捕获容易出错的错误,例如错别字,在分配前使用vars等。

2.1.3 Cons

pylint 并不完美。要利用它,有时我们需要:

  • 围绕它写
  • 禁止其警告
  • 对其进行改进

2.1.4 Decision

确定在你的代码中运行 pylint

如果不适当,请禁用警告,以免隐藏其他问题。要取消显示警告,可以设置行级注释:

1
dict = 'something awful'  # Bad Idea... pylint: disable=redefined-builtin

pylint 警告均由符号名称(empty-docstring) 标识, Google 特定警告以 g- 开头。

如果从符号名称中看不到禁用的原因,请添加说明。以这种方式进行禁用的优势在于,我们可以轻松地搜索抑制并重新进行禁用。

要获取 pylint 警告列表可以这样操作:

1
pylint --list-msgs

获取特定消息的详细信息,执行:

1
pylint --help-msg=C6409

推荐使用 pylint:disable 而不是使用旧的 pylint:disable-msg 形式。

可以通过删除函数开头的变量来消除未使用的参数警告。记得添加注释解释为什么删除。 Unused 就可以了。例如:

1
2
3
def viking_cafe_order(spam, beans, eggs=None):
del beans, eggs # Unused by vikings.
return spam + spam + spam

取消警告的其他常见形式包括使用 _ 作为未使用参数的标识符,或在参数名称前加上 unused_ 前缀,
或将其分配给 _ 。虽然可以这么做,但不再鼓励。一些中断调用程序按名称传递参数,并且不强制要求参数实际上未使用。

2.2 Imports

import 语句仅用在包和模块,不要用在类和函数上。对于 typing module 导入是特例。

2.2.1 定义

Re-usability mechanism for sharing code from one module to another.

2.2.2 优点

命名空间管理约定很简单。每个标识符的来源以一致的方式表示; x.Obj 表示 Obj 对象定义在 x 模块中。

2.2.3 缺点

模块名称仍然可以冲突。一些模块名称很长。

2.2.4 判断

  • 使用 import x 导入一个包或模块。
  • 使用 from x import yx 包的前缀, y 是不带