python 开发规范 预览版

本文主要参考 pep8和jumpserver开发规范，结合实际，进行修改，欢迎提出修改意见。

代码检查工具

• pylint
• PyCharm --> code --> RefORMat Code 格式化当前文件代码格式
• pycharm --> 右击项目 --> Inspect Code 根据pep8格式检查当前项目

基本的代码布局

导入

import x
from x import y
from x import y as z

禁止import  x,y

异常

使用 as

try:
    raise Error
except Error as error:
    pass

缩进

1. python 严格采用4个空格的缩进，任何 Python 代码都都必须遵守此规定。
2. 字符,    后面空一个格

最大行长度

限制最大120个字符。

长语句缩进

编写长语句时，可以使用换行符""换行。在这种情况下，下一行应该与上一行的最后一个“.”句点或“=”对齐，或者是缩进4个空格符。

this_is_a_very_long(function_call, 'with many parameters') \
    .that_returns_an_object_with_an_attribute

MyModel.query.filter(MyModel.Scalar > 120) \
             .order_by(MyModel.name.desc()) \
             .limit(10)

如果你使用括号“()”或花括号“{}”为长语句换行，那么下一行应与括号或花括号对齐：

this_is_a_very_long(function_call, 'with many parameters',
                    23, 42, 'and even more')

对于元素众多的列表或元组，在第一个“[”或“(”之后马上换行：

items = [
    'this is the first', 'set of items', 'with more items',
    'to come in this line', 'like this'
]

空行

顶层函数与类之间空两行，此外都只空一行。不要在代码中使用太多的空行来区分不同的逻辑模块。

def hello(name):
    print('Hello %s!' % name)

class MyClass(object):
    """This is a simple docstring."""

    def __init__(self, name):
        self.name = name

    def get_annoying_name(self):
        return self.name.upper() + '!!!!111'

空格规则

单目运算符与运算对象之间不空格（例如，-，~等），即使单目运算符位于括号内部也一样。
双目运算符与运算对象之间要空格

exp = -1.05
value = (item_value / item_count) * offset / exp
value = my_list[index]
value = my_dict['key']

字符格式化

使用 f'{name}{value}'

比较

• 任意类型之间的比较，使用“isinstance(L, list)”和“not isinstance(L, list)”
• 与单例（singletons）进行比较时，使用 is 和 is not。
• 永远不要与True或False进行比较（例如，不要这样写：foo == False，而应该这样写：if not foo）。
• 否定成员关系检查, 使用 foo not in bar，而不是 not foo in bar。

命名约定

• 类名称：采用骆驼拼写法（CamelCase。
• 变量名：小写_以及_下划线（lowercase_with_underscores）。
• 方法与函数名：小写_以及_下划线（lowercase_with_underscores）。
• 常量：大写_以及_下划线（UPPERCASE_WITH_UNDERSCORES）。
• 预编译的正则表达式：name_re。
• 受保护的元素以一个下划线为前缀。双下划线前缀只有定义混入类（mixin classes）时才使用。
• 如果使用关键词（keyWords）作为类名称，应在名称后添加后置下划线（trailing underscore）。 允许与内建变量重名，不要在变量名后添加下划线进行区分。如果函数需要访问重名的内建变量，请将内建变量重新绑定为其他名称。
• 命名要有寓意, 不使用拼音,不使用无意义简单字母命名 (循环中计数例外 for i in)
• 命名缩写要谨慎, 尽量是大家认可的缩写
• 尽量 避免使用全局变量, 用类变量来代替

函数和方法的参数：

• 类方法：cls 为第一个参数。
• 实例方法：self 为第一个参数。
• property函数中使用匿名函数（lambdas）时，匿名函数的第一个参数可以用 x 替代， 例如：display_name = property(lambda x: x.real_name or x.username)。
• 禁止参数里面 直接写 字符id，用其他替代，例如 asset_id

文档注释（Docstring，即各方法，类的说明文档注释）

所有文档字符串均以 reStructuredText 格式编写，方便 Sphinx 处理。文档字符串的行数不同，布局也不一样。 如果只有一行，代表字符串结束的三个引号与代表字符串开始的三个引号在同一行。 如果为多行，文档字符串中的文本紧接着代表字符串开始的三个引号编写，代表字符串结束的三个引号则自己独立成一行。 （有能力尽可能用英文, 否则请中文优雅注释）

def foo():
    """This is a simple docstring."""

def bar():
    """This is a longer docstring with so much information in there    
    that it spans three lines.  In this case, the closing triple quote    
    is on its own line.    
    """

文档字符串应分成简短摘要（尽量一行）和详细介绍。如果必要的话，摘要与详细介绍之间空一行。

注释（Comment）类 函数 注释

def AvailableZones(self, instance_charge_type, region_id):
    """
    功能: 可用区
    :param instance_charge_type: 计费方式
    :param region_id:    地域
    :return:  ['cn-huhehaote-a', 'cn-huhehaote-b']
    """

模块头部

模块文件的头部包含有 utf-8 编码声明（如果模块中使用了非 ASCII 编码的字符，建议进行声明），以及标准的文档字符串。

#!/usr/bin/env python3.6
# -*- coding: utf-8 -*-

参考:Http://docs.jumpserver.org/zh/docs/python_style_guide.html