Python编程规范+最佳实践

# 前言
`Python`之禅是影响`Python`编程语言设计的`19`条原则，也是`Python`编码规范的核心理念。

- 优美胜于丑陋（`Python`以编写优美的代码为目标）
- 明了胜于晦涩（优美的代码应当是明了的，命名规范，风格相似）
- 简洁胜于复杂（优美的代码应当是简洁的，不要有复杂的内部实现）
- 复杂胜于凌乱（如果复杂不可避免，那代码间也不能有难懂的关系，要保持接口简洁）
- 扁平胜于嵌套（优美的代码应当是扁平的，不能有太多的嵌套）
- 间隔胜于紧凑（优美的代码有适当的间隔，不要奢望一行代码解决问题）
- 可读性很重要（优美的代码是可读的）
- 即便假借特例的实用性之名，也不可违背这些规则（这些规则至高无上）
- 不要包容所有错误，除非你确定需要这样做（精准地捕获异常，不写`except:pass`风格的代码）
- 当存在多种可能，不要尝试去猜测
- 而是尽量找一种，最好是唯一一种明显的解决方案（如果不确定，就用穷举法）
- 虽然这并不容易，因为你不是`Python`之父（这里的`Dutch`是指`Guido`）
- 做也许好过不做，但不假思索就动手还不如不做（动手之前要细思量）
- 如果你无法向人描述你的方案，那肯定不是一个好方案；反之亦然（方案测评标准）
- 命名空间是一种绝妙的理念，我们应当多加利用（倡导与号召）

`PEP8`是`Python`官方推出的编码规范。本规范以`PEP8`编码规范作为出发点编写。编码规范的第一原则是 提升代码的可读性，如果项目是从零开始请遵守该编码规范，如果不是，在项目和该规范出现冲突时，项目自身的规范优先。每一种规范分为强制和推荐。强制是必须遵守的规范，推荐是最佳实践。

# 代码布局
## 强制
1. 统一使用`4个空格`缩进
2. 单行最大长度为`100`
3. 行数超过规定，建议用小括号`()`将多行内容连接起来，而不推荐使用反斜杠`\`进行连接。
4. 不要在代码末尾加`分号`，也不要用`分号`将两条命令写在同一行
5. 空行使用：
	a. 函数之间用两个空行隔开
	b. 类之间用两个空行隔开
	c. 类中方法用一个空行隔开
	d. 函数中不同逻辑代码块之间可适当插入空行
6. 空格使用：
	a. 在二元运算符两边都要有空格。二元运算包括：算术(`+ - * / **`)、赋值(`=，+=，-=`)、比较(`==, <, >, !=, in, not in, is, is not`)、逻辑运算(`and or not`)、位运算(`& | ! ~ >> <<`)
	b. 函数关键字参数=两侧不需要空格。例：`res = func(name="Tom")`
	c. 逗号后面要加空格，但是如果后面是小括号则不用。例：`List=[1, 2, 4]`
	d. 冒号前不加空格，冒号后要加空格。但是切片里前后都不可加空格 。例：`Dict = {key: value}`
	e. 不要为对齐赋值语句而使用的额外空格

### 推荐
1. `import`或函数存在续行的情况，遵守挂行缩进对齐
	- 第一行不应该有参数
	- 使用缩进以区分自己是续行
### 推荐
```python
def ats_import_dataset(
    db: Session = Depends(deps.get_db),
    ats_import: schemas.AtsDataSetImport,
    current_user: models.User = Depends(deps.get_current_active_user),
    controller_client: ControllerClient = Depends(deps.get_controller_client),
    background_tasks: BackgroundTasks,
 ) -> Dict:
```
2. 在二元运算符之前应该换行,而不是在运算符之后换行
### 推荐
```python
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)
```
### 不推荐
```python
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)
```

# 命名
## 强制
1. 普通变量使用下划线分隔命名法，即蛇形命名法。例：`max_value`
2. 变量名和Python关键字冲突，在变量末尾追加下划线。例：`type_`
3. 避免使用双下划线开头并结尾的名称，该命令方式为python保留字。例：`__ init__`用于类初始化
4. 常量用全大写字母，用下划线连接。例：`MAX_VALUE`
5. 函数名遵循蛇形命名法。例：`def get_user_info`
6. 类名使用驼峰命名法。例：`class ControllerService`
7. 类中私有属性和方法用单下划线开头。该定义仅为君子约定，实例化可以访问。例：`def _previate_fun()`
8. 类中不希望被继承的变量用双下划线开头。例：`__user_info`
9. 模块应该用简短全小写的名字，如果为了提升可读性，下划线也是可以用的。
10. 包使用简短全小写的名字，但不建议用下划线。

## 推荐
1. 使用枚举值、常量值替换没有意义的数字。
2. 永远不要使用`l`(小写的`L`)，`O`(大写的`O`)，`I`(大写的`I`)作为单字符变量名，这些字符无法区分。
3. 描述性强。在可接受的长度范围内，变量名所指向的内容描述越精确越好。尽量不要用那些过于宽泛的词来作变量名 。推荐：`last_login_datetime`不推荐：`datetime`。
4. 尽量短。命名尽量不超过5个单词。变量名要结合代码情景和上下文，可以通过函数名，类名，模块名自解释。
```python
def get_expired_vip_users:
    pass
    # 返回过期vip用户数
    # 推荐
    users_count = 0
    # 不推荐
    expired_vip_users_count = 0
```
5. 配型匹配
- 使用`is，has， allow`等开头来命名表示boolean类型。例：`is_vip、has_error、all_empty`
- 使用`_id`结尾，`length/count`开头结尾的单词表示`int`类型。例：`user_id,host_id,max_length,users_count`

# 函数
## 强制
1. 函数设计要尽量短小，·100行·是一个参考值
2. 一个函数只做一件事，保证函数语句粒度的一致性
3. 禁止使用可变类型作为函数参数默认值，有惨痛教训：一个·Python Bug·干倒了估值·1.6·亿美元的公司
```python
# 明令禁止
 List = []
 def fun(num, arr=List)
    pass
```

## 推荐
- 要将`self`作为实例方法的的第一个参数。
- 要将`cls`作为类静态方法的第一个参数。
- 如果函数的参数名和已有的关键词冲突，参考变量名和关键字重复的处理方法
- 函数圈复杂度可以衡量函数逻辑，圈复杂度不应该超过10(大概10个`if else`)

# 模块导入
## 强制
1. 一个`import`语句导入一个模块
## 推荐
```python
import os
import sys
```
## 不推荐
```python
import sys, os
```
2. 导入总是位于文件的顶部，在模块注释和文档字符串之后，在模块的全局变量与常量之前
3. 导入应该按照以下顺序分组,每一组导入之间加入空行：
	- 标准库导入
	- 相关第三方库导入
	- 本地应用/库特定导入
4. 推荐使用绝对路径导入
5. 禁止使用通配符的导入，污染命名空间。例：`from module import *`

## 推荐
	1. 如果导入的模块名较长，使用 as 给模块重命名。例：`from moudle import module_fun as mf`

# 注释
## 强制
1. 代码块注释使用`#`， 接口注释使用`"""`
2. 块注释应该至少离开代码`2个`空格，`#`后面跟一个空格
3. 公共函数，重要的函数必须写接口注释
4. 逻辑复杂，难以理解，脚本代码等情况必须要有注释
5. 代码修改要同步更新注释

## 推荐
1. 待实现的功能用`TODO`注释
2. 不要用注释描述代码，而是说清楚功能或逻辑

# 真值判断
## 推荐
1. 对于容器类型来说，判断空值不要用长度等于0，可以使用空序列布尔值为`False`这个属性来判断。
- `python`中 0、`None`、空字符串、空列表、空元组、空字典、空集合、空集合，都可以视为`False`，`if`判断可以视为`False`。其他情况都为`True`。推荐：
```python
user_list = []
if not user_list:
    pass
if user_list:
    pass
```
## 不推荐
```python
user_list = []
if len(user_list):
    pass
if not len(user_list):
    pass
```
2. 布尔类型的判断，推荐使用`if value`。
```python
greeting = True
推荐: if greeting:
不推荐: if greeting is True:
不推荐: if greeting == True:
```
3. 对空值`None`的判断优先使用`None`为`False`属性，需要显示判断逻辑更加清晰时可以使用`is`关键字。例：`if value is None`。
4. 空值判断使用`if value is not None`而不是`if not value is None`

# 错误捕获
## 强制
1. 对于无法预知错误类型，使用异常捕获来保证流程正常。如网络请求
2. 异常捕获的颗粒度是行，对大段代码进行`try-catch`，这是不负责任的表现
3. 异常捕获时分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。
4. 异常不要用来做流程控制，条件控制
5. 捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之。禁止在捕获错误之后使用`pass`不处理。如果不想处理它或不能处理，请将该异常抛给它的调用者。
6. 禁止在`finally`块中使用`return`，`finally`是最后执行的代码，`return`会覆盖正常流程的`return`。

## 推荐
1. 存在`if else`嵌套复杂的逻辑时，使用`try except`优化
2. 可以通过预先检查进行规避时，推荐不要异常捕获来处理
3. 错误的返回推荐异常类而不是变量

# 工程结构
## 推荐
`Python`项目没有其他语言如`Java`的`Maven`来构造固定的工程文件目录，结合`Python`社区推荐的工程目录制定推荐结构如下：
```
sample_project
 ├── readme.md
 ├── docs
 │   ├── api.yml
 │   └── public_read.md
 ├── requirements.txt
 ├── app
 │   ├── __init__.py
 │   ├── core.py
 │   └── helpers.py
 ├── config
 │   ├── mysql.py
 ├── deploy
 │   ├── __init__.py
 │   └── run.sh
 ├── db
 │
 ├── utils
 │
 └── tests
     ├── __init__.py
     └── test_basic.py
```
- `readme.md`: 项目说明文件
- `docs`: 存放项目文档，包括功能详细说明，`api docs`等
- `requirements.txt`: 存放软件依赖的外部`Python`包列表
- `app`: 存放项目接口主要代码的目录
- `config`: 存放项目配置文件，如`mysql`，`redis`等配置项
- `deploy`：存放部署文件，部署脚本等。如`docker-compse.yml`文件
- `db`: 存放数据库相关代码
- `utils`: 存放项目工具代码，通常和业务无关
- `tests`: 存放单元测试文件