Python编码规范

1、inf-qa python编码规范修改记录no 版本号修改内容简介修改日期修改人1v1.0全文2010-11-18 崔晶晶2 v1.1 增加 case 编码规范2013-05-10 崔晶晶目录inf-qa python 编码规范 . 11. 介绍 . 31.1. 开发背景 . 31.2. 语言 . 31.2.1. 版本 . 31.3. 规范文档 . 32. 一致性的建议. 33. 代码的布局 . 33.1. 缩进 . 33.2. tab键还是空格 . 43.3. 行的最大长度. 43.4. 空行 . 43.5. 编码 . 44. 导入 . 45. 空格 . 55.1. 其它建议 . 56. 注

2、释 . 66.1 注释块 . 66.2 行内注释 . 67. 文档化 . 78. 版本注解 . 79. 命名约定 . 79.1. 描述：命名风格. 79.2. 说明：命名约定. 89.2.1. 应避免的名字. 89.2.2. 模块名 . 89.2.3. 类名 . 89.2.4. 异常名 . 89.2.5. 全局变量名 . 89.2.6. 函数名 . 99.2.7. 方法名和实例变量名. 99.2.8. 继承 . 910. 设计建议 . 911. demo . 10 12. the zen of python. 12 1. 介绍1.1.开发背景为了提高组内自动化开发效率，避免重复开发，对组内各模

3、块已开发的自动化lib 库、case 中常用的操作、以及其他工具的调用接口进行汇总，管理出dsqa 组内自动化case开发的基础库。1.2.语言基础库采用python 开发。需要调用的相关二进制工具的地方，为降低开发成本，暂采用直接调该工具，封出python 方法接口。1.2.1. 版本python 版本较多，为避免上下版本的兼容性问题，开发采用统一版本。python 2.6.2/2.7.x 1.3.规范文档为了方便维护、 他人阅读使用，整理出该编码规范文档。请大家开发时遵循本规范进行更开发。本文档参考自guido 的 python 风格指南一文. 并从 barrys style guide中

4、添加了部分内容，以及我的个人建议。2. 一致性的建议整个项目的开发中，请尽量保持一致性，尤其是一个模块或者一个函数中的一致性更为重要。因此存在这样的一个问题：由于不同模块的lib 库开发人不同，编码规范也可能不同，整合起来会显得不够“和谐”。还是希望各模块lib 库负责人做相应的修改，尽量“和谐”。3. 代码的布局3.1.缩进众所周知， python 是通过缩进来进行代码布局的。使用vi 可以在 /.vimrc 中配置几个空格来代表一个tab，从而来布局python 函数的缩进。3.2.tab键还是空格python 里有一句叫“以用空格为荣，以用tab 键为耻”。但全用空格时确实很麻烦。因此，

5、这里不限定用tab 键还是空格。但记住：不可混用！你可以选择全部使用tab 键，这样也不会出错。3.3.行的最大长度类似于函数中的行注释、函数体等，如果某一行很长，则导致换行折叠观看，很影响美观，而且还不利于阅读。因此，对顺序排放的的大块文本（文档字符串或注释），推荐长度限制在 72 个字节 内。推荐使用反斜杠续行。3.4.空行用两行分割顶层函数和类的定义。用一行分割类成员方法的定义。在一个函数内使用空行时请注意谨慎使用于一个逻辑段。3.5.编码在 python 2.4 之后内核已经开始支持unicode 了。无论什么情况下，使用 utf-8才是王道 ！1 # -*- coding:utf-8

6、 -*-2 4. 导入通常应该在单独行中使用导入。例如：no: import sys, os yes: import sys import os 但是这样也是可以的：from types import stringtype, listtype imports 应该放在文件的顶部，仅在模块注释和文档字符串之后，在模块的全局变量和常量之前。imports 也是有顺序的：1)python 标准库的import ；2)第三方库的import ；3)自定义的库的import ；并且在每组的import 之间使用一行空行分割。5. 空格以下地方 不推荐 出现空格 : 1)紧挨着圆括号,方括号和花括号的如:

7、spam( ham 1 , eggs: 2 ).写成 spam(ham1, eggs: 2) . 2)紧贴在逗号 ,分号或冒号前的如: if x = 4 : print x , y ; x , y = y , x. 写成if x = 4: print x, y; x, y = y, x. 3)紧贴着函数调用的参数列表前开式括号的如: dict key = list index . 写成dictkey = listindex . 4)紧贴在索引或切片下标开始的开式括号前如: dict key = list index. 写成 dictkey = listindex . 5)在赋值 (或其它 )运

8、算符周围的用于和其它并排的一个以上的空格,如: 1 x = 1 2 y = 2 3 long_variable = 3 写成1 x = 1 2 y = 2 3 long_variable = 3 5.1.其它建议始终在这些二元运算符两边放置一个空格:赋值 (=), 比较 (=, , !=, , =, in, not in, is, is not), 布尔运算(and, or, not). 按你的看法在算术运算符周围插入空格. 始终保持二元运算符两边空格的一致. 一些例子 : 1 i = i+1 2 submitted = submitted + 1 3 x = x*2 - 1 4 hypot2

9、 = x*x + y*y 5 c = (a+b) * (a-b) 6 c = (a + b) * (a - b) 不要在用于指定关键字参数或默认参数值的=号周围使用空格,例如 : 1 def complex(real, imag=0.0): 2 return magic(r=real, i=imag) 不要将多条语句写在同一行上. no: if foo = blah: do_blah_thing() yes: if foo = blah: do_blah_thing() no: do_one(); do_two(); do_three() yes: do_one() do_two() do_t

10、hree() 6. 注释注释必须跟代码保持一致，当你想修改代码时，建议优先修改注释。注释必须是完整的句子。如果注释是一个句子或者短语，请首字母大写。如果注释很短，建议省略句末的句号。注释块通常由一个或多个由完整句子构成的段落组成，每个句子应该以句号结尾。注释请使用英文。约定使用统一的文档化注释格式有助于良好的习惯和团队的进步。6.1注释块注释块通常应用于跟随着一些(或者全部 )代码并和这些代码有着相同的缩进层次。注释块中每行以#和一个空格开始(除非他是注释内的缩进文本)。注释块内的段落以仅含单个#的行分割。注释块上下方最好有一空行包围(或上方两行下方一行，对一个新函数定义段的注释)。6.2行内

11、注释行内注释应该至少用两个空格和语句分开. 它们应该以 #和单个空格开始. x = x+1 # increment x 如果语意是很明了的,那么行内注释是不必要的,事实上是应该被去掉的. 不要这样写 : x = x+1 # increment x x = x+1 # compensate for border 但是有时 ,这样是有益的: x = x+1 # compensate for border 7. 文档化为配合pydoc;epydoc,doxygen 等等文档化工具的使用，应该一直遵守编写好的文档字符串的约定。多行文档字符串结尾的 应该单独成行，例如: return a foobang

12、 optional plotz says to frobnicate the bizbaz first. 对单行的文档字符串,结尾的 在同一行也可以。8. 版本注解1 _version_ = $revision: 1.0.0.0 $ 这个行应该包含在模块的文档字符串之后,所有代码之前 ,上下用一个空行分割。当然也可以这样：12version: 1.0.0.0 3跟其他相关信息（如author 、copyright 、date 等）一起。9. 命名约定现有的库的命名约定想必比较混乱，但对于今后即将开发的新的模块应尽量遵循该约定开发。对于已有的模块存在不同风格的，保证内部的一致性是首选的。9.1.

13、描述：命名风格一般的命名风格大家都清楚。这里说几个特殊的注意点：1） 单下划线作为前导， 如：_single_begin， 这是弱的内部使用标识，例如使用 “from m import *”的时候不会被导入；2） 单下划线作为结尾的，如：single_end_，这一般用于跟python 关键词冲突；3） 双下划线前导，如：_double_begin ，类私有名；4） 双下划线前导 +结尾，如： _double_begin_and_end_ ，特殊对象或属性，存在于用户控制的命名空间中，如：_init_，_import_ 等。有时可以被用户定义，用于触发某个特殊行为，如运算符重载。9.2. 说明

14、：命名约定9.2.1. 应避免的名字永远不要用：1） 小写字母“ l” （小写的“ l” ） ；2） 大写字母“ o” ；3） 大写字母“ i” （读音 eye） ；作为单字符的变量名，因为不利于跟数字“0”和“ 1”很好的区分开来。当要用小写字母“l”时，请用大写字母“l”代替。9.2.2. 模块名模块应该是不含下划线的，简短的，小写的名字。因为模块名被映射到文件名, 有些文件系统大小写不敏感并且截短长名字, 模块名被选为相当短是重要的-这在 unix 上不是问题 , 但当代码传到mac 或 windows 上就可能是个问题了。9.2.3. 类名几乎没有例外，类名总是使用首字母大写、驼峰命名

15、单词串的约定。9.2.4. 异常名首字母大写、驼峰命名9.2.5. 全局变量名这个的约定跟用于函数的约定差不多。那些模块，应该在那些不想被导入的全局变量(还有内部函数和类)前加一个下划线)。9.2.6. 函数名函数名应该为小写、动宾短语，可能用 下划线 风格单词以增加可读性。如：open_file() 9.2.7. 方法名和实例变量名小写、动宾短语、下划线风格以增加可读性。单前导下划线仅用于不打算作为类的公共接口的内部方法。双前导下划线表示类私有的名字，python 将这些名字和类名连接在一起。如果类 foo 有一个属性名为_a, 它不能以 foo._a 访问，如果你非要访问，还是可以通过 f

16、oo._foo_a得到访问权。通常，双前导下划线应该只用来避免与类中的属性发生名字冲突。9.2.8. 继承始终要确定一个类中的方法和实例变量是否要被公开。同样， 确定你的属性是否应为私有的。私有与非公有的区别在于：前者永远不会被用在一个派生类中，而后者可能会。私有属性必须有两个前导下划线，无后置下划线。非公有属性必须有一个前导下划线，无后置下划线。公共属性没有前导和后置下划线，除非它们与保留字冲突。10.设计建议1） 与像none 之类的单值进行比较的时候，应永远使用：is或 is not ：当你本意是 if x is not none 时，对写成 if x 要小心，因为例如当你测试一个默认为

17、none的变量或参数是否被设置为其它值时，这个其它值可能是一个在布尔上下文中为假的值。2） 基于类的异常总是好过基于字符串的异常：模块和包应该定义它们自己的域内特定的基异常类, 基类应该是内建的exception 类的子类。还始终包含一个类的文档字符串。例如: 1 class messageerror(exception): 2 base class for errors in the email package. 3） 使用字符串方法代替字符串模块：因为字符串方法总是非常的快。4） 在检查前缀或后缀时避免对字符串进行切片：用 startswith() 和 endswith() 代替，因为它们

18、是明确的并且错误更少。例如：no: if foo:3 = bar: yes: if foo.startswith(bar): 5） 对象类型的比较应该始终用isinstance() 代替直接比较类型：例如 : no: if type(obj) is type(1): yes: if isinstance(obj, int): 6） 检查一个对象是否是字符串时,紧记它也可能是unicode字符串。7） 对序列 ,(字符串、 列表、 元组 )，使用空列表是false这个事实， 因此 if not seq或if seq比 if len(seq)或if not len(seq)好。8） 书写字符串文字

19、时不要依赖于有意义的后置空格，这种后置空格在视觉上是不可辨别的。9） no chinese ！包括注释，也请尽量使用英文。10）自动化 case中请使用python logging模块设定日志级别打印日志，而不要大量使用 print 输出。11）print时请使用 ” %d” 、” %s” 等标准输出格式，请勿str和变量混合连接使用。11.demo 1#!/usr/bin/env python2# -*- coding:utf-8 -*-34_version_ = 1.0.0.05_author_ = cuijingjing6_date_ = thu nov 18 14:52:47 cst

20、20107_copyright_= baidu89import sys10import os11import shutil12import stat1314 -classopfile: 1516 -def _init_(self): 17pass1819 -def replace_file(self, file_name, replace_from, replace_to ): 2021note: replace some string in a file, link sed22parameter file_name: the file you want to deal with23param

21、eter replace_from: string you want to replace24parameter replace_to: the string you want to replace to2526if not os.path.exists(file_name): 27print file not exists.28exit() 2930file_name = os.path.abspath (file_name) 3132ori_file = open (file_name,r).read() 33if ori_file.find(replace_from) != -1: 34

22、if shutil.copyfile(file_name, file_name + .bak) != -1: # backup first35replace_in = open(file_name + .bak, r) 36replace_out = open(file_name, w) 37s = replace_in.read() 38replace_out .write(s.replace (replace_from, replace_to ) 39else : 40print error not find + replace_from + in + file_name + 41exit

23、() 4243if _name_ = _main_: 44op_file = opfile() 45op_file.replace_file(/home/cuijingjing/dgl/bin/test/test.c , cuijingjing , nnrand48) 46这里我写的demo，也不一定完全百分百地跟规范一模一样，但至少能确保他人阅读起来不会费劲。用 epydoc 生成文档后，epydoc 会识别出你的注释信息，并在moudle 中体现出来，如下图：对于类方法， 它的参数 （parameters）是什么， 它是用来干什么的（ note）都一目了然。12.the zen of python 最后附上 the zen of python ，希望我们的开发越来越规范，整个团队进步越来越快！the zen of pythonby tim peters beautiful is better than ugly. expli