Python开发规范（FastAPI项⽬）
⼀、概述
出于整个团队代码可读性、可维护性考量，有必要约定⼀套Python开发基本规范，从⽽提升项⽬可持续性开发，提升代码开发效率等。鉴于此，制订以下Python开发规范⽂档，本规范⽂档⼀经确认，Python开发⼈员需按照此⽂档规范进⾏项⽬Python后端的开发，对本⽂档不合理或不对之处请及时提出，在讨论统⼀意见后进⾏修改。
提⾼代码质量
统⼀项⽬代码风格
⽅便代码⾃审、他审依据参考
提升协作开发效率
促进个⼈成长
⼆、开发环境
如⽆特殊需要，选择 Python 3.7+ 版本解释器
开发环境尽量保持和服务器环境⼀致，以免开发完成后上线时发⽣意外的环境兼容问题
三、项⽬⽬录结构
|- main (存放启动项⽬⼊⼝⽂件)
|- control(存放和数据库交互的控制器⽂件)
|- item / model (存放数据结构⽂件)
|- api
|- internal (存放内部api处理⽂件)
- routers.py (路由模块)
- dependencies.py (依赖项模块)
|- external (存放外部api处理⽂件)
-
routers.py (路由模块)
- dependencies.py (依赖项模块)
| - ...（其他分类api）
|- docs (存放相关⽂档)
|- setting (存放配置⽂件)
|- static (存放静态资源⽂件)
|- templates (存放模板⽂件)
|- utils (存放三⽅、⼯具、常量、异常等公⽤模块)
|- log (存放临时⽇志⽂件)
|- task (存放异步任务⽂件 Celery 等)
- f.py
-
README.md
-
- xx.sh (启停或其他脚本)
具体结构可根据具体项⽬略做调整和修改
四：命名规范
Type Public Internal
项⽬lower_with_under
模块lower_with_under lower_with_under
包lower_with_under
类CapWords CapWords
异常CapWords
函数lower_with_under()_lower_with_under()
函数lower_with_under()_lower_with_under()
Type Public Internal
全局/类 常量CAPS_WITH_UNDER_CAPS_WITH_UNDER
全局/类 变量lower_with_under_lower_with_under
实例变量lower_with_under_lower_with_under (protected) or __lower_with_under (private)
⽅法名lower_with_under()_lower_with_under() (protected) or __lower_with_under() (private)
函数/⽅法 参数lower_with_under
局部变量lower_with_under
不要使⽤中⽂拼⾳，尽量不要使⽤数字
尽量命名语义化
应该避免的名称
单字符名称, 除了计数器和迭代器.
包/模块名中的连字符(-)
双下划线开头并结尾的名称(Python保留, 例如__init__)
命名约定
所谓”内部(Internal)”表⽰仅模块内可⽤, 或者, 在类内是保护或私有的.
⽤单下划线(_)开头表⽰模块变量或函数是protected的(使⽤from module import *时不会包含).
⽤双下划线(__)开头的实例变量或⽅法表⽰类内私有.
将相关的类和顶级函数放在同⼀个模块⾥. 不像Java, 没必要限制⼀个类⼀个模块.
对类名使⽤⼤写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该⽤⼩写加下划线的⽅式(如lower_with_under.py).五、编码风格规范
主要参考
⾏长度
每⾏不超过 120 个字符
例外:
长的导⼊模块语句
注释⾥的URL
不要使⽤反斜杠连接⾏.
Python会将 圆括号, 中括号和花括号中的⾏隐式的连接起来 , 你可以利⽤这个特点. 如果需要, 你可以在表达式外围增加⼀对额外的圆括号.
如果⼀个⽂本字符串在⼀⾏放不下, 可以使⽤圆括号来实现隐式⾏连接.
在注释中，如果必要，将长的URL放在⼀⾏上.
括号
宁缺⽏滥的使⽤括号
除⾮是⽤于实现⾏连接, 否则不要在返回语句或条件语句中使⽤括号. 不过在元组两边使⽤括号是可以的.
缩进
⽤4个空格来缩进代码
绝对不要⽤tab, 也不要tab和空格混⽤. 对于⾏连接的情况, 你应该要么垂直对齐换⾏的元素(见 ⾏长度 部分的⽰例), 或者使⽤4空格的悬挂式缩进(这时第⼀⾏不应该有参数):
空⾏
顶级定义之间空两⾏, ⽅法定义之间空⼀⾏
顶级定义之间空两⾏, ⽐如函数或者类定义. ⽅法定义, 类定义与第⼀个⽅法之间, 都应该空⼀⾏. 函数或⽅法中, 某些地⽅要是你觉得合适, 就空⼀⾏.
空格
按照标准的排版规范来使⽤标点两边的空格
括号内不要有空格.
不要在逗号, 分号, 冒号前⾯加空格, 但应该在它们后⾯加(除了在⾏尾).
参数列表, 索引或切⽚的左括号前不应加空格.
在⼆元操作符两边都加上⼀个空格, ⽐如赋值(=), ⽐较(==, <, >, !=, <>, <=, >=, in, not in, is, is not), 布尔(and, or, not). ⾄于算术操作符两边的空格该如何使⽤, 需要你⾃⼰好好判断. 不过两侧务必要保持⼀致.
当’=’⽤于指⽰关键字参数或默认参数值时, 不要在其两侧使⽤空格.
不要⽤空格来垂直对齐多⾏间的标记, 因为这会成为维护的负担(适⽤于:, #, =等):
注释
确保对模块, 函数, ⽅法和⾏内注释使⽤正确的风格.
⽂档字符串
Python有⼀种独⼀⽆⼆的的注释⽅式: 使⽤⽂档字符串. ⽂档字符串是包, 模块, 类或函数⾥的第⼀个语
句. 这些字符串可以通过对象的__doc__成员被⾃动提取, 并且被pydoc所⽤. (你可以在你的模块上运⾏pydoc试⼀把, 看看它长什么样). 我们对⽂档字符串的惯例是使⽤三重双引号”“”( PEP-257 ). ⼀个⽂档字符串应该这样组织: ⾸先是⼀⾏以句号, 问号或惊叹号结尾的概述(或者该⽂档字符串单纯只有⼀⾏). 接着是⼀个空⾏. 接着是⽂档字符串剩下的部分, 它应该与⽂档字符串的第⼀⾏的第⼀个引号对齐. 下⾯有更多⽂档字符串的格式化规范.
由于很难界定是否需要注释，尽量都写上⽂档字符串，复杂的代码块加上代码块注释。
函数和⽅法
下⽂所指的函数，包括函数, ⽅法, 以及⽣成器.
⼀个函数必须要有⽂档字符串, 除⾮它满⾜以下条件:
外部不可见
⾮常短⼩
简单明了
⽂档字符串应该包含函数做什么, 以及输⼊和输出的详细描述. 通常, 不应该描述”怎么做”, 除⾮是⼀些复杂的算法. ⽂档字符串应该提供⾜够的信息, 当别⼈编写代码调⽤该函数时, 他不需要看⼀⾏代码, 只要看⽂档字符串就可以了. 对于复杂的代码, 在代码旁边加注释会⽐使⽤⽂档字符串更有意义.
统⼀ 使⽤ 格式⽂档字符串，
类
类应该在其定义下有⼀个⽤于描述该类的⽂档字符串. 如果你的类有公共属性(Attributes), 那么⽂档中应该有⼀个属性(Attributes)段.
并且应该遵守和函数参数相同的格式.
块注释和⾏注释
最需要写注释的是代码中那些技巧性的部分. 如果你在下次 代码审查 的时候必须解释⼀下, 那么你应该现在就给它写注释. 对于复杂的操作, 应该在其操作开始前写上若⼲⾏注释. 对于不是⼀⽬了然的代码, 应在其⾏尾添加注释. 为了提⾼可读性, 注释应该⾄少离开代码2个空格.
另⼀⽅⾯, 绝不要描述代码. 假设阅读代码的⼈⽐你更懂Python, 他只是不知道你的代码要做什么.
类
如果⼀个类不继承⾃其它类, 就显式的从object继承. 嵌套类也⼀样.
字符串
使⽤ f-strings⽅法对字符串进⾏拼接.
避免在循环中⽤+和+=操作符来累加字符串. 由于字符串是不可变的, 这样做会创建不必要的临时对象, 并且导致⼆次⽅⽽不是线性的运⾏时间. 作为替代⽅案, 你可以将每个⼦串加⼊列表, 然后在循环结束后⽤ .join 连接列表. (也可以将每个⼦串写⼊⼀个 cStringIO.StringIO 缓存中.)
在同⼀个⽂件中, 保持使⽤字符串引号的⼀致性. 使⽤单引号’或者双引号”之⼀⽤以引⽤字符串, 并在同⼀⽂件中沿⽤. 在字符串内可以使⽤另外⼀种引号, 以避免在字符串中使⽤.
为多⾏字符串使⽤三重双引号”“”⽽⾮三重单引号’‘’. 当且仅当项⽬中使⽤单引号’来引⽤字符串时, 才可能会使⽤三重’‘’为⾮⽂档字符串的多⾏字符串来标识引⽤. ⽂档字符串必须使⽤三重双引号”“”. 不过要注意, 通常⽤隐式⾏连接更清晰, 因为多⾏字符串与程序其他部分的缩进⽅式不⼀致.
⽂件和sockets
除⽂件外, sockets或其他类似⽂件的对象在没有必要的情况下打开, 会有许多副作⽤, 例如:
1. 它们可能会消耗有限的系统资源, 如⽂件描述符. 如果这些资源在使⽤后没有及时归还系统, 那么⽤于处理这些对象的代码会将资源消耗
殆尽.
2. 持有⽂件将会阻⽌对于⽂件的其他诸如移动、删除之类的操作.
3. 仅仅是从逻辑上关闭⽂件和sockets, 那么它们仍然可能会被其共享的程序在⽆意中进⾏读或者写操作. 只有当它们真正被关闭后, 对于
它们尝试进⾏读或者写操作将会抛出异常, 并使得问题快速显现出来.
⽽且, 幻想当⽂件对象析构时, ⽂件和sockets会⾃动关闭, 试图将⽂件对象的⽣命周期和⽂件的状态绑定在⼀起的想法, 都是不现实的. 因为有如下原因:
1. 没有任何⽅法可以确保运⾏环境会真正的执⾏⽂件的析构. 不同的Python实现采⽤不同的内存管理技术, ⽐如延时垃圾处理机制. 延时
垃圾处理机制可能会导致对象⽣命周期被任意⽆限制的延长.
2. 对于⽂件意外的引⽤，会导致对于⽂件的持有时间超出预期(⽐如对于异常的跟踪, 包含有全局变量等).
推荐使⽤ “with”语句 以管理⽂件
python中文文档
with open("")as hello_file:
for line in hello_file:
print line
对于不⽀持使⽤”with”语句的类似⽂件的对象，使⽤ contextlib.closing()
import contextlib
with contextlib.closing(urllib.urlopen("/"))as front_page:
for line in front_page:
print line
TODO注释
为临时代码使⽤TODO注释, 它是⼀种短期解决⽅案. 不算完美, 但够好了.
导⼊格式
每个导⼊应该独占⼀⾏
导⼊总应该放在⽂件顶部, 位于模块注释和⽂档字符串之后, 模块全局变量和常量之前. 导⼊应该按照从最通⽤到最不通⽤的顺序分组:
1. 标准库导⼊
2. 第三⽅库导⼊
3. 应⽤程序指定导⼊
每种分组中, 应该根据每个模块的完整包路径按字典序排序, 忽略⼤⼩写.
语句
通常每个语句应该独占⼀⾏.
访问控制
在Python中, 对于琐碎⼜不太重要的访问函数, 你应该直接使⽤公有变量来取代它们, 这样可以避免额外的函数调⽤开销. 当添加更多功能时，你可以⽤属性(property)来保持语法的⼀致性.
另⼀⽅⾯, 如果访问更复杂, 或者变量的访问开销很显著, 那么你应该使⽤像 get_foo() 和 set_foo() 这样的函数调⽤. 如果之前的代码⾏为允许通过属性(property)访问 , 那么就不要将新的访问函数与属性绑定. 这样, 任何试图通过⽼⽅法访问变量的代码就没法运⾏, 使⽤者也就会意识到复杂性发⽣了变化.
Main

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。