前言

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

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

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

代码布局

强制 ：

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

推荐 ：

1. import或函数存在续行的情况，遵守挂行缩进对齐

• 第一行不应该有参数
• 使用缩进以区分自己是续行

推荐：

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. 在二元运算符之前应该换行,而不是在运算符之后换行

推荐：

income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

不推荐：

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个单词。变量名要结合代码情景和上下文，可以通过函数名，类名，模块名自解释。

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 亿美元的公司

# 明令禁止
 List = []
 def fun(num, arr=List)
    pass

import os
import sys

import sys, os

user_list = []
if not user_list:
    pass 

if user_list:
    pass

user_list = [] 
if len(user_list):
    pass 
if not len(user_list): 
    pass

greeting = True
推荐: if greeting:
不推荐: if greeting is True:
不推荐: if greeting == True:

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