Python编码格式

1.介绍

1.1 开发背景

​ 为了提高组内自动化开发效率，避免重复开发，对组内各个模块已开发的自动化lib库，case中常见的操作，以及其他跟工具的调用接口进行汇总，管理出dsqa组内自动化case开发的基础。

1.2. 语言

​ 基础库采用python开发。需要调用的相关二进制工具的地方，为降低开发成本，暂采用直接调用该工具，封出python方法接口。

1.3 规范文档

​ 为了方便维护，他人阅读使用，整理出编码规范文档，请大家开发是遵循本规范进行更开发。

本文档参考自Guido的《Python风格指南》一文，，并用《Barry style guide》中添加的部分内容，以及我的个人建议。

一致性的建议

​ 整个项目的开发中，请保持一致性，尤其是模块或者是一个函数中的一致性更为重要。

因此存在一个这样的问题：由于不同的lib库开发人不同，编码风格也可能不同，整合起来显得不够“和谐”。

还是希望各模块lib库负责人相对应的修改，显得“和谐”。

3.代码的布局

3.1 缩进

​ 总所周知。Python是通过缩进进行代码布局，使用vi可以在-v.vimrc中配置几个空格来代表tab，从而来布局，Python函数的缩进。

3.2 Tob键还是空格键

​ Python里有一句叫“一空格为荣，tab为耻”，但全用tab很麻烦，因此：我们不能限定使用什么，不可混用。

​ 你可以选择全部用tab 这样不会出错

行的最大长度

​ 类似于函数中的行注释，函数体，如果某一行很长。则导致换行折叠观看，很影响美观，而且不利于阅读，因此，对顺序排放的大块文本，（文档字符串或注释），推荐长度在72个字符内。

​ 推荐使用反斜杠化行

3.4 空行

​ 用两行分割顶层函数和类的定义

​ 用一行分割类成员方法的定义

​ 在一个函数内使用空格时请注意谨慎使用于一个逻辑段

3.5编码

在python2.4之后内核已经开始支持Unicode

无论什么情况下，使用UTF-8才是王道

#-*-coding：utf-8-*-
#coding=utf-8

4.导入

通常应该在单独行中使用导入。

例如：

No：import sys,os
Yes: import sys
	 import os

但是这样也是可以

from types import StringType,Listypr

​ import应该放在文件的顶部

Import 也是有顺序的

（1）python标准库的import

（2）第三方库的import

（3）自定义的库的import

并且在每组import导入用空行分割

5.空格

以下地方不推荐出现空格：
1）紧贴着圆括号，方括号和花括号的
如：'span( name [ 1 ] , { a : 1 } )'改成：‘span(name[1], {a: 1})’
2）紧贴在逗号，分号，冒号前的
如：'if x == 1 : x , y : x , y = y , x '改成: 'if x == 1: x, y: x, y = y, x ’
3）紧贴着函数调用的参数列表前开式括号的
如：‘dict [‘key’] = list [ 1 ]’ 改成 ‘dict[‘key’] = list[1]’
4）紧贴在索引或切片下标开始的开式括号前
如：‘dict [‘key’] = list [ 1 ]’ 改成 ‘dict[‘key’] = list[1]’

（5）在赋值（或其他）运算符周围的用于和其他并排的一个以上的空格;

错误
1			X		= 1
2			y		= 2
3			aaaaaaa = 3
正确
x = 1
y = 2
aaaaa = 3

5.1其他建议

始终在这些二元运算符两边放置一个空格：赋值(=)，比较(==,<,>,!=,<=,>=,in,not,in,is,is not),布尔运算(and,or,not).

按你的看法在算术运算符周围插入空格。始终保持二元运算符两边空格的一致

i = i + 1
b = b + 1
x = x*2-1

不要在于指定关键字参数或默认参数值的“=”号周围使用空格，例如：

1  def complex(real,imag=0.0):
2      return magin(r=real,i=imag)

不要将多条语句写在同一行上

No:  if foo == 'blah': do_blah_thing()
Yes:      if foo == 'blan':
            do_blan_thing()
            
No: do_one();do_two();do_three()
Yes: do_one()
     do_two()
     do_three()

注释

注释必须跟代码保持一致，当你想修改代码是先修改注释

注释必须是完整的句子

如果注释是一个句子或者短句，请首字母大写

如果注释很短，建议省略句末的句号

注释块通常由一个或多个由完整句子构成的段落组成，每个句子应该以句号结尾

注释请使用英文

约定使用同意的文档注释格式有助于良好的习惯和团队的进步。

6.1 注释块

注释块通常应用于跟随着一些（或者全部）代码并和这些代码有着相同的缩进层次。

注释块 每次以“#”和一个空格开始（除非他是注释内的缩进文本）

注释块的段落以及含单个“#”的行分割

注释块上下最好是有一空行包围（或上方两行或下方一行，对一个新函数定义段的注释）

6.2行内注释

行内注释只是两个空格和语句分开，他们应该以“#”和单个空格开始

如果语句是很明了的，那么行内注释是不必要的，事实上是应该去除掉的，不要这样写

x=x+1             #increment x

8版本更新

1		_version_="$

这个行应该包含模块的文档字符串之后，所以代码之前，上下用一个空行分割，当然也可以这样

1'''
2@version	1.0.0.0
2'''

更其他相关信息（如：author，copyright，date等）一起。

9 命名约定

​ 现有库的命名比较混乱，但对于今后即将开发新的模块遵循约定开发，对于一样的模块存在不同的风格的，保证内部的一致性是首选的。

9.1描述：命名风格

一般的命名风格大家都清楚，这里说几个特殊的例子

（1）单下划线作为前导：如：_single_begin,这是弱的内部标识符，例如“from 模块 import”的时候不会被导入

（2）单下划线作为结尾的，如：singe_end_.这一般不会

（3）双下划线前导，如：_double_begin,类私有名

（4）双下划线前导+结尾，如：double_begin_and,特殊对象或属性，存在于用户控制的命名空间中，如_init_,_import_等。有时可以被用户定义，用于触发某个特殊行为，如运算符重载。

9.2.1 应避免的

永远不要使用

1）小写的l

2）大写的O和零

3）大写的I

作为单字符的变量名，因为不利于跟数字1和0很好的区分开来

当要用小写字母l时，请用大写L来代替

9.2.2 模块名

​ 模块应该是不含下划线的，简短的，小写的名字。

​ 因为模块名被映射到文件名，有些系统 对大小写不敏感并且截短长名字。模块名被选择为相当短是重要的——这在Unix上不是问题，但当代码传到Mac或Windows上就可能是个问题了。

9.2.3 类名

几乎没有例外，类名总是使用首字母大写，驼峰命名单词串的约定。

9.2.4 异常名

首字母大写，驼峰命名

9.2.5 全局变量名

这个的约定跟用于函数的约定差不多。

那些模块，应该在那些不想被导入的全局变量（还有函数和类）前加一个下划线。

9.2.6函数名

函数名应该为小写，动宾短语，可能用于下划线风格单词以增加可读性，如ope_file

9.2.7 方法名和实例变量名

​ 小写，动宾短语，下划线风格以增加可读性

​ 单前导下划线仅用于不打算作为类的公共接口的内部方法。

​ 双前导下划线表示类私有的名字，python将这些名字和类名连接在一起。

如果类foo有一个属性名为a，它不能以Foo.a访问，如果你非要访问，还是可以通过Foo._Foo_a得到访问权。通常，双前导下划线通常应该只用来于避免类中属性发生名字冲突。

9.2.8 继承

10.设计建议

1.与像None之类的单值进行比较的时候，应永远使用:is’或’is not’
当你的本意是"if x is not None"时，对写成"if x"要小心，因为例如当你测试一个默认为None的变量或参数是否被设置为其他值时,这个其他值可能是-个在布尔上下文中为假的值
2.基于类的异常总是好过基于字符串的异常
模块和包应该定义它们自己的域内特定的基异常类，吉磊应该是内建的Exception类的子类不始终包含一 个类的文档字符串

1 class MessageError(Exception)
2     """Base class for errors in the email package."""

​ 3.使用字符串方法代替字符串模块因为字符串方法总是非常的快
​ 4.在检查前缀或后缀时避免对字符串进行片
​ 用startswith()和endswith()代替，因为它们是明确的并且错误更少
​

1 class MessageError(Exception)
2     """Base class for errors in the email package."""

​ 5.对象类型的比较始终用isinstance()代替直接比较类型
​

No: if foo[:3] == "bar":
Yes: if foo.stratswith("bar"):

​ 6.检查一个对象 是否是字符串时，紧记它也可能是unicode字符串
​ 7.对序列，(字符串，列表，元组),使用空列表是false这个事实，因此"if not seq" 比"if len(seq)" 或"if not len(seq)“好
​ 8.书写字符串文字时不要依赖于有意义的后置空格，这种后置空格在视觉上不可辨认
​ 9.No Chinese!包括注释，也请尽量使用英文
​ 10.,自动化case中请使用python logging模块设定日志级别打印日志，而不要大量使用print()输出
​ 11.print()时请使用”%d","%s "等标准输出格式，请勿str和变 量混合连接使用