Python编程规范和格式化工具

摘要:

PSF & PEP

PSF(Python Software Foundation),Python的官方组织。PSF 提供的文档包括:

PEP 是 PSF 写出、收纳、提供给社区参考使用、包含新特性、规范性等内容的说明文档。

PEP在 github 上撰写、管理,自动编译html、同步到 网站 上,从2000年开始创建,至今(2019.5)仍非常活跃,如果是python的developer,建议star或watch它,实时跟踪。

PEP分了8类: 核心类、已提交、已接收、讨论中、讨论完、归档、拒绝、废弃 。

  • 有些pep很庞大,如:pep8(python编程规范);也有些很简短,如:pep7(c编程规范)
  • 有些pep很一本正经,如:pep569(Python 3.8 Release Schedule);有些也很搞怪,如:pep20(Zen of Python,20条禅学)

要贡献 PEP,需要参考 pep12 的模板来写,并且 PEP 不是用 markdown 写的,而是 ReStructuredText,也是标记(markup)语言,语法比 markdown 稍复杂一点点,这里有一些语法说明:

普通 Python 开发人员必读的PEP有:

  • 编码规范
    • PEP8 :Python 编码规范
    • PEP7 :C 编码规范
  • 文档规范
    • PEP256 :文档系统工作机制
    • PEP257 :docstrings Conventions
    • PEP258 :注释与文档转换工具
    • PEP287 :reStructuredText 书写规则

PEP8 Style Guide for Python Code

核心类 pep 是 PEPs of PEPs,目前只有9个, PEP8 位列其中,内容是 Python 的编码规范,Python开发人员必读文档之一。

PEP8 从2001年创建,至今有141次提交:

修改(提交)集中在2002、 2012~2016年,2019已相对稳定:

参与撰写的人不少,但top3都是python官方的人:

PEP8 极简版

PEP8 有网友翻译: python代码风格指南(PEP8中文版)

下面我来整理一份PEP8的极简版,相比上面的网友翻译,增补了:

  • Module级dunder
  • 尾随逗号

极简版正文:

写“可读的代码”

代码的使用频率上看:读取远大于编写,所以一定要写“可读的代码”

每级缩进4空格,不允许tab和空格混用

入参和if分开讨论

# 函数定义的入参比函数名多1级缩进
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# 函数调用的入参可对准左括号 or 悬挂缩进1级
foo = long_function_name(var_one, var_two,
                         var_three, var_four)
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

# if条件语句跨行时缩进:加1级即可
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

最大行宽79字符,文本块 72 字符,极限 99 字符

  • 以前通常在二元运算符(+-*/ and or…)之后续行
  • 现在推荐在二元运算符之前续行
    income = (gross_wages
            + taxable_interest
            + (dividends - qualified_dividends)
            - ira_deduction
            - student_loan_interest)

空行要尽量节约使用

  • 顶层函数和Class之间可以用2个空行
  • Class内的方法之间用1个空行

源文件字符编码尽量使用 utf-8

  • ASCII 和 utf-8 的源文件不需要“编码声明”
  • 标准库更严格:符号 必须 用ASCII,其他 尽量 英文字母
  • 注释or字符串可以用非ASCII字符 \x \u \U \N
: str1='\xE4'
: print(str1)
ä

: str2 = '\u4f60\u597d'
: print(str2)
你好

: str3='你好'.encode('unicode-escape')
: print(str3)
b'\\u4f60\\u597d'

import 每行导入1个模块

from xxx import *

Module级dunder必须在 __future__ 之后,其他import之前

  • dunder (double underscore, 双下划线)
  • 最早python对 __all__ 这种符号称为魔法变量、魔法函数,后来为了破除迷信,称为 double underscore method,但太长了,被简称为 dunder symbol、dunder method……
  • Module级的 dunder 有2个约束
    from __future__ import ...
    
from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys

python 字符串的单引号与双引号等效

空格的讲究有很多

  • 括号(圆括号、方括号)内避免空格
    • 左括号之前避免空格
  • 逗号、冒号、分号之前避免空格,之后可有
    • 索引中的冒号前后都要避免空格
  • 赋值等操作符前后不能因为对齐而添加多个空格
  • 二元运算符两边放置一个空格
    • 优先级高的运算符或操作符的前后不建议有空格
    • 关键字参数和默认值参数的前后不要加空格
# 错误示范:
spam( ham[ 1 ], { eggs: 2 } ) # 括号里面太多空格
ham[1: 9], ham[1 :9], ham[1:9 :3] # 索引冒号前后不应有空格
long_variable = 3
x             = 1  # 不能为了对齐等号而加空格
i=i+1 # =和+左右都要有空格
submitted +=1 # += 右边没有空格
x = x * 2 - 1 # *优先级高,左右不应有空格
def complex(real, imag = 0.0): # 默认参数的=左右不能有空格
    return magic(r = real, i = imag)

function annotations = 前后有空格, : 和 -> 前无后有

python3 中引入了 function annotations,它是一种注释性质的语法,用于声明入参的类型和默认值。

  • 2006年的 PEP3107 首先定义了 Function Annotations
  • 2014年的 PEP484 补充和修订了 Function Annotations
  • 2016年,又发展出了 PEP526 ,定义了 Variable Annotations
import enforce

@enforce.runtime_validation
def add_int(a: int, b: int = 0)-> int:
    return a + b

print(add_int.__annotations__)
  • 表明入参a是int型,b是int型且默认值0,返回值int型
  • func.__annotations__ 返回函数入参注释信息
  • 有@enforce则强制类型检查,不匹配报错;不加 @enforce 则只做告警,不报错
  • function annotations 的编程规范要求
    • =前后要有空格
    • 冒号和”->”的前无,后有。
      def add_int(a:int, b: int=0) -> int: # 错误示范,有3处错误
      def add_int(a: int, b: int = 0)-> int: # 正确示范

尾随逗号在Tuple中重要,List中无效;分行中有利,单行中冗余

尾随逗号(Trailing Commas)

FILES0 = ('setup.cfg')  # 0
FILES1 = ('setup.cfg',) # 1
FILES2 = 'setup.cfg',   # 2
FILES3 = ['setup.cfg', 'tox.ini']    # 3
FILES4 = ['setup.cfg', 'tox.ini', ]  # 4
FILES5 = [                           # 5
    'setup.cfg',
    'tox.ini',
    ]
  • 类型:0是str,1/2是tuple,3/4是list
: print(type(FILES0),type(FILES1),type(FILES2),type(FILES3),type(FILES4))                                                         
<class 'str'> <class 'tuple'> <class 'tuple'> <class 'list'> <class 'list'>
  • 1==2 —— Tuple中尾随逗号是重要的
In [42]: FILES1==FILES2
Out[42]: True
  • 3==4==5 —— List中尾随逗号是无效的
In [43]: FILES3==FILES4==FILES5
Out[43]: True
  • 5 中每行增加尾随逗号是有意义的,可以减少新增行时的工作量
  • 4 中单行增加尾随逗号是没有意义的。

注释书写规范参考 PEP257

  • 与代码自相矛盾的注释比没注释更差。修改代码时要优先更新注释!
  • 注释段落中的每个句子应该以句号+2个空格结束。
  • 文档化注释 (或称为:可生成文档的注释)需遵守 PEP257
    • 将来有空可以单讲一篇,先挖个坑吧

命名:可用一张表格说清

程序猿常见的命名风格多样:

Naming Styles举例使用场景备注
单个小写字母b变量名避免使用小写l(易与1,I混)
单个大写字母B变量名避免使用大写O(易与0混)、I
小写串lowercase变量名,包名,模块名模块名对应文件名,有线系统文件名不区分大小写
带下划线的小写lower_case_with_underscores函数名,类的公开方法 
大写串UPPERCASE常量通常在模块级别定义
带下划线的大写串UPPER_CASE_WITH_UNDERSCORES常量同上
驼峰命名法 
首字母大写的单词串
CapitalizedWords(CapWords)Class名专有名次缩写可全大写,如HTTP
匈牙利命名法 
混合大小写,首单词小写
mixedCase python抵制 
极少特殊情况下用于函数名
带下划线,首字母大写Capitalized_Words_With_Underscores python抵制,丑陋
短前缀分组+匈牙利或驼峰bsp_getPower python抵制,与C划清界限
单前置下划线_single_leading_underscore用于不想被外部使用的全局变量 
或局部变量 
类的非公开方法和实例变量
弱内部使用 
weak “internal use”
单后置下划线single_trailing_underscore_def func(class_='name')用于避免与 Python关键词的冲突
双前置下划线__double_leading_underscore类Foo中的 __bar 会变成 _Foo__bar当用于命名类属性,会触发名字重整
双前后下划线__dunder_func__Dunder(魔法)函数不要自己发明这样的名字
__all__

编程建议

下面就不单纯是格式(format)的问题了,而是有利于程序运行的内容。

  • 要明白自己在用哪个python解释器
    • 官方整理出来好几十个
      • CPython: https://www.python.org/downloads/ 官网下载的既是
      • CPython衍生的 stacklessPython, wpython, microPython…
      • PyPy :Python in Python
      • Jython :Python in Java
      • IronPython :Python in C#
      • ActivePython
      • WinPython
    • CPython及其衍生底层是用C实现的,所以对C/Python API都有完美支持。非C语言实现的编译器虽然某些操作会快一些,但最大的问题是不支持某些只有C接口的库,如:numpy、scipy……
    • 不同的编译器之间效率有差别,官方建议你仔细研究、斟酌
  • if foo is not None 优于 if not foo is None
  • if foo == None 用法错误
  • 比较排序操作最好实现完整6个操作: __eq__, __ne__, __lt__, __le__, __gt__, __ge__
  • 变量赋值不要用lambda,而要用def,如: f = lambda x: 2*x #不推荐
  • 空”except:”子句(相当于except Exception)会捕捉SystemExit和KeyboardInterrupt异常,难以用Control-C中断程序,并可掩盖其他问题。只适用于2种情况
    • 打印出或记录了traceback,至少让用户将知道已发生错误
    • 代码需要做一些清理工作,并用 raise转发了异常,try…finally可以捕捉到它
  • 本地资源用with,使用with的资源要有独立的enter、exit方法
  • 函数或者方法在没有返回时要明确返回None
def foo(x):
    if x < 0:
        return  # No!请 return None
    return math.sqrt(x)
  • 使用字符串方法而不是string模块
    • Python不支持单字符类型,单字符在 Python 中也是作为一个字符串
# 字符串方法
>>> type(str)   # str是python关键字
<class 'type'>
>>> STR="Hello World"
>>> type(STR)
<class 'str'>
>>> str.lower(STR)
'hello world'
>>> STR.lower() # str.xxx() == STR.xxx()
'hello world'
>>> STR[::-1]   # 翻转字符串
'dlroW olleH'

>>> import string
>>> STR = "Hello {0}"
>>> f = string.Formatter()
>>> f.format(STR,"world") 
'Hello world'
>>> STR.format("World")
'Hello World
  • 字符串方法中检查前后缀:使用 .startswith()和.endswith()代替字符串切片
>>> STR[:5]=="Hello"        # 切片 —— No!
True
>>> STR.startswith("Hello") # Yes!
True
  • 使用isinstance()代替对象类型的比较
if isinstance(obj, int):    # Yes!
if type(obj) is type(1):    # No!
  • 判断序列(字符串、list、tuple)为空:
if not seq:     # Yes!
if len(seq):    # No!
  • 不要用 == 进行布尔比较
if greeting:            # Yes!
if greeting == True     # No!
if greeting is True:    # Worse

自动格式化工具

要实现 PEP8 中的大部分条目并不难,但要持之以恒、实现所有条目,应该还是挺难的。

一个人要实现 PEP8 中的条目并不难,但要保证一个团队都做到,应该还是挺难的。

如果有一个自动格式化工具,当我 Ctrl-S 保存文件的时候实时帮我按 PEP8 美化一下,上面2个问题就都不是问题了。

YAPF

Google 出品的 YAPF 可以满足你这方面的几乎所有需求。

$ pip install yapf
$ yapf [options] [files [files ...]]

常用的 options 有:

  • --diff : 输出diff文件,不修改源文件
  • --style STYLE :
    • “pep8” or “google”
    • 如果当前目录下有 .style.yapf 或 setup.cfg 文件,则从此文件中读取配置项
    • .style.yapf 文件示例
[yapf]
based_on_style = pep8
spaces_before_comment = 4
split_before_logical_operator = true

Black

Black 帮我们实现这个愿望。

用了 Black,相当于放弃了自己的编码风格,完全由 Black 来接手,一个团队的代码就像一个人写的 —— 至少样子上是。

经过一段时间之后,个人手写水平也能提高,逐步逼近 PEP8 的要求。

$ pip install black
$ black [options] [mypythonfile 或 dir]
  • 常用的 options 有:
    • -t [py27|py33|py34|py35|py36|py37|py38]
      • Black 会自动逐个试探每个文件的python版本,应用不同的风格
    • --check :只检查,不修改源文件
    • --diff : 输出diff文件,不修改源文件
    • --include XXX , --exclude XXX : 操作目录时的筛选器

比较

ItemYAPFBlack点评
LicenseApache2.0MIT两者都允许修改后闭源,即允许只发布二进制版本,但必须附带License。Apache要求每个文件头上都要附带,MIT只需要根目录下放一份即可。
AuthorGooglePython所以Black只支持PEP8,YAPF则可定制
创建日期2015-03-182018-03-143月是个好季节
提交次数1000+500+截至2019.5

找一段代码实战比较一下,从左至右依次是:原始文件、black处理后的文件、yapf依pep8处理过的文件

  • 第1行:每次只import1个model —— 没有帮我改过来
  • 第2行:dunder 变量放置在 import 之前 —— 没有帮我改过来
  • 第9-18行:空格、空行,black和yapf都控制的不错
    • 第17行:google把索引中的冒号两边去掉了空格
  • 第19-23行:因为没有超过80列,续行都合并到1行了
  • 第24-25行:PEP8中推荐的写法,black、yapf都做了修正
  • 第28-32行:PEP8中推荐的写法,black微调,yapf大修 —— black稍优
  • 第34行:函数注释都能控制冒号左右的空格
  • 第37行:要用is而不是==来比较None —— 都没修改过来

可以看出 black 和 yapf 能做的和 PEP8 比较还是有限,且目前都还在 书写美化 上下功夫,在 代码优化 上不足。

  • 1
    点赞
  • 0
    评论
  • 2
    收藏
  • 打赏
    打赏
  • 扫一扫,分享海报

©️2022 CSDN 皮肤主题:大白 设计师:CSDN官方博客 返回首页

打赏作者

大咖爱爬虫

你的鼓励将是我创作的最大动力

¥2 ¥4 ¥6 ¥10 ¥20
输入1-500的整数
余额支付 (余额:-- )
扫码支付
扫码支付:¥2
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值