# Naming Conventions 命名规范

Python 库的命名规范很乱，从来没能做到完全一致。但是目前有一些推荐的命名标准。新的模块和包(包括第三方框架)应该用这套标准，但当一个已有库采用了不同的风格，推荐保持内部一致性。

## Overriding Principle 最重要的原则

那些暴露给用户的 API 接口的命名，应该遵循反映使用场景而不是实现的原则。

## Descriptive: Naming Styles 描述：命名风格

有许多不同的命名风格。这里能够帮助大家识别正在使用什么样的命名风格，而不考虑他们为什么使用。

以下是常见的命名方式：

* b(单个小写字母)

* B(单个大写字母)

* lowercase 小写字母

* lower_case_with_underscores 使用下划线分隔的小写字母

* UPPERCASE 大写字母

* UPPER_CASE_WITH_UNDERSCORES 使用下划线分隔的大写字母

* CapitalizedWords(或者叫 CapWords，或者叫 CamelCase 驼峰命名法 —— 这么命名是因为字母看上去有起伏的外观[5](https://blog.csdn.net/ratsniper/article/details/78954852#fn:4 "See footnote"))。有时候也被称为 StudlyCaps。

注意：当在首字母大写的风格中用到缩写时，所有缩写的字母用大写，因此，HTTPServerError 比 HttpServerError 好。

* mixedCase(不同于首字母大写，第一个单词的首字母小写)

* Capitalized_Words_With_Underscores(巨丑无比！)

也有用唯一的短前缀把相关命名组织在一起的方法。这在 Python 中不常用，但还是提一下。比如，os.stat()函数中包含类似以 st_mode，st_size，st_mtime 这种传统命名方式命名的变量。(这么做是为了与 POSIX 系统的调用一致，以帮助程序员熟悉它。)

X11 库的所有公共函数都加了前缀 X。在 Python 里面没必要这么做，因为属性和方法在调用的时候都会用类名做前缀，函数名用模块名做前缀。

另外，下面这种用前缀或结尾下划线的特殊格式是被认可的(通常和一些约定相结合)：

* _single_leading_underscore：(单下划线开头)弱“内部使用”指示器。比如 from M import * 是不会导入以下划线开始的对象的。

* single_trailing_underscore_：(单下划线结尾)这是避免和 Python 内部关键词冲突的一种约定，比如：Tkinter.Toplevel(master, class_=’ClassName’)

* `__double_leading_underscore`：(双下划线开头)当这样命名一个类的属性时，调用它的时候名字会做矫正(在类 FooBar 中，`__boo` 变成了`_FooBar__boo`；见下文)。

* `__double_leading_and_trailing_underscore__`：(双下划线开头，双下划线结尾)“magic”对象或者存在于用户控制的命名空间内的属性，例如：`__init__`,`__import__` 或者`__file__`。除了作为文档之外，永远不要命这样的名。

## Prescriptive: Naming Conventions 约定俗成：命名约定

### Names to Avoid 应避免的名字

永远不要使用字母‘l’(小写的 L)，‘O’(大写的 O)，或者‘I’(大写的 I)作为单字符变量名。

在有些字体里，这些字符无法和数字 0 和 1 区分，如果想用‘l’，用‘L’代替。

### Package and Module Names 包名和模块名

模块应该用简短全小写的名字，如果为了提升可读性，下划线也是可以用的。Python 包名也应该使用简短全小写的名字，但不建议用下划线。

当使用 C 或者 C++ 编写了一个依赖于提供高级(更面向对象)接口的 Python 模块的扩展模块，这个 C/C++ 模块需要一个下划线前缀(例如：_socket)

### Class Names 类名

类名一般使用首字母大写的约定。

在接口被文档化并且主要被用于调用的情况下，可以使用函数的命名风格代替。

注意，对于内置的变量命名有一个单独的约定：大部分内置变量是单个单词(或者两个单词连接在一起)，首字母大写的命名法只用于异常名或者内部的常量。

### Exception Names 异常名

因为异常一般都是类，所有类的命名方法在这里也适用。然而，你需要在异常名后面加上“Error”后缀(如果异常确实是一个错误)。

### Global Variable Names 全局变量名

(我们希望这一类变量只在模块内部使用。)约定和函数命名规则一样。

通过 from M import * 导入的模块应该使用 **all** 机制去防止内部的接口对外暴露，或者使用在全局变量前加下划线的方式(表明这些全局变量是模块内非公有)。

### Function Names 函数名

函数名应该小写，如果想提高可读性可以用下划线分隔。

大小写混合仅在为了兼容原来主要以大小写混合风格的情况下使用(比如 threading.py)，保持向后兼容性。

### Function and method arguments 函数和方法参数

始终要将 self 作为实例方法的的第一个参数。

始终要将 cls 作为类静态方法的第一个参数。

如果函数的参数名和已有的关键词冲突，在最后加单一下划线比缩写或随意拼写更好。因此 class_ 比 clss 更好。(也许最好用同义词来避免这种冲突)

### Method Names and Instance Variables 方法名和实例变量

遵循这样的函数命名规则：使用下划线分隔小写单词以提高可读性。

在非共有方法和实例变量前使用单下划线。

通过双下划线前缀触发 Python 的命名转换规则来避免和子类的命名冲突。

Python 通过类名对这些命名进行转换：如果类 Foo 有一个叫 `__a` 的成员变量， 它无法通过 `Foo.__a` 访问。(执着的用户可以通过 `Foo._Foo__a` 访问。)一般来说，前缀双下划线用来避免类中的属性命名与子类冲突的情况。

注意：关于 `__names` 的用法存在争论(见下文)。

### Constants 常量

常量通常定义在模块级，通过下划线分隔的全大写字母命名。例如： MAX_OVERFLOW 和 TOTAL。

### Designing for inheritance 继承的设计

始终要考虑到一个类的方法和实例变量(统称：属性)应该是共有还是非共有。如果存在疑问，那就选非共有；因为将一个非共有变量转为共有比反过来更容易。

公共属性是那些与类无关的客户使用的属性，并承诺避免向后不兼容的更改。非共有属性是那些不打算让第三方使用的属性；你不需要承诺非共有属性不会被修改或被删除。

我们不使用“私有(private)”这个说法，是因为在 Python 中目前还没有真正的私有属性(为了避免大量不必要的常规工作)。

另一种属性作为子类 API 的一部分(在其他语言中通常被称为“protected”)。有些类是专为继承设计的，用来扩展或者修改类的一部分行为。当设计这样的类时，要谨慎决定哪些属性时公开的，哪些是作为子类的 API，哪些只能在基类中使用。

贯彻这样的思想，一下是一些让代码 Pythonic 的准则：

* 公共属性不应该有前缀下划线。

* 如果公共属性名和关键字冲突，在属性名之后增加一个下划线。这比缩写和随意拼写好很多。(然而，尽管有这样的规则，在作为参数或者变量时，‘cls’是表示‘类’最好的选择，特别是作为类方法的第一个参数。)

注意 1：参考之前的类方法参数命名建议

* 对于单一的共有属性数据，最好直接对外暴露它的变量名，而不是通过负责的 存取器(accessor)/突变(mutator) 方法。请记住，如果你发现一个简单的属性需要成长为一个功能行为，那么 Python 为这种将来会出现的扩展提供了一个简单的途径。在这种情况下，使用属性去隐藏属性数据访问背后的逻辑。

注意 1：属性只在 new-style 类中起作用。

注意 2：尽管功能方法对于类似缓存的负面影响比较小，但还是要尽量避免。

注意 3：属性标记会让调用者认为开销(相当的)小，避免用属性做开销大的计算。

* 如果你的类打算用来继承的话，并且这个类里有不希望子类使用的属性，就要考虑使用双下划线前缀并且没有后缀下划线的命名方式。这会调用 Python 的命名转换算法，将类的名字加入到属性名里。这样做可以帮助避免在子类中不小心包含了相同的属性名而产生的冲突。

注意 1：只有类名才会整合进属性名，如果子类的属性名和类名和父类都相同，那么你还是会有命名冲突的问题。

注意 2：命名转换会在某些场景使用起来不太方便，例如调试，`__getattr__()`。然而命名转换的算法有很好的文档说明并且很好操作。

注意 3：不是所有人都喜欢命名转换。尽量避免意外的名字冲突和潜在的高级调用。

## Public and internal interfaces 公共和内部的接口

任何向后兼容保证只适用于公共接口，因此，用户清晰地区分公共接口和内部接口非常重要。

文档化的接口被认为是公开的，除非文档明确声明它们是临时或内部接口，不受通常的向后兼容性保证。所有未记录的接口都应该是内部的。

为了更好地支持内省(introspection)，模块应该使用 `__all__` 属性显式地在它们的公共 API 中声明名称。将 `__all__` 设置为空列表表示模块没有公共 API。

即使通过 `__all__` 设置过，内部接口(包，模块，类，方法，属性或其他名字)依然需要单个下划线前缀。

如果一个命名空间(包，模块，类)被认为是内部的，那么包含它的接口也应该被认为是内部的。

导入的名称应该始终被视作是一个实现的细节。其他模块必须不能间接访问这样的名称，除非它是包含它的模块中有明确的文档说明的 API，例如 os.path 或者是一个包里从子模块公开函数接口的 `__init__` 模块。