python之开发规范（Python开发规范）

python之开发规范（Python开发规范）

命名规范

Python之父推荐的规范

应该避免的名称

1.单字符名称2.包/模块名中使用连字符(-)而不使用下划线(_)3.双下划线开头并结尾的名称（如__init__）

命名约定

1.所谓”内部(Internal)”表示仅模块内可用, 或者, 在类内是保护或私有的.2.用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).3.用双下划线(__)开头的实例变量或方法表示类内私有.4.将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.5.对类名使用大写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该用小写加下划线的方式(如lower_with_under.py).

注释规范

文档字符串

Python使用文档字符串作为注释方式: 文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的doc成员被自动提取, 并且被pydoc所用. 我们对文档字符串的惯例是使用三重双引号”“”( PEP-257 ).

一个文档字符串应该这样组织:1. 首先是一行以句号, 问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行). 接着是一个空行.2. 接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐.

"""A user-created :class:`Response ` object. Used to xxx a :class: `JsonResponse `, which is xxx:param data: response data:param file: response files Usage:: >>> import api >>> rep = api.Response(url="行内注释和代码至少要有两个空格分隔2. 注释由#和一个空格开始

x = x + 1 # Compensate for border

模块

每个文件应该包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD, LGPL, GPL), 选择合适的样板.

# -*- coding: utf-8 -*-# (C) JiaaoCap, Inc. 2017-2018# All rights reserved# Licensed under Simplified BSD License (see LICENSE)

函数和方法

一个函数必须要有文档字符串, 除非它满足以下条件:1. 外部不可见2. 非常短小3. 简单明了

文档字符串应该包含函数做什么, 以及输入和输出的详细描述文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了对于复杂的代码, 在代码旁边加注释会比使用文档字符串更有意义.

def simple_func(method, timeout) """Constructs and sends a :class:`Request `. :param method: method for the new :class:`Request` object. :param timeout: (optional) How many seconds to wait for the server to send data before giving up, as a float, or a :ref:`(connect timeout, read timeout) ` tuple. :type timeout: float or tuple :return: :class:`Response ` object :rtype: requests.Response Usage:: >>> import requests >>> req = requests.request('GET', ' """

类

类应该在其定义下有一个用于描述该类的文档字符串. 如果你的类有公共属性(Attributes), 那么文档中应该有一个属性(Attributes)段. 并且应该遵守和函数参数相同的格式.

class HTTPAdapter(BaseAdapter): """The built-in HTTP Adapter for urllib3. Provides a general-case interface for Requests sessions to contact HTTP and HTTPS urls by implementing the Transport Adapter interface. :param pool_connections: The number of urllib3 connection pools to cache. :param max_retries: The maximum number of retries each connection should attempt. Usage:: >>> import requests >>> s = requests.Session() >>> a = requests.adapters.HTTPAdapter(max_retries=3) >>> s.mount('a) """ def __init__(self, pool_connections, max_retries): self.pool_connections = pool_connections self.max_retries = max_retries

块注释和行注释

对于复杂的操作, 应该在其操作开始前写上若干行注释. 对于不是一目了然的代码, 应在其行尾添加注释.

# We use a weighted dictionary search to find out where i is in# the array. We extrapolate position based on the largest num# in the array and the array size and then do binary search to# get the exact number.if i & (i-1) == 0: # true iff i is a power of 2

行长度

每行不超过80个字符不要使用反斜杠连接行Python会将 圆括号, 中括号和花括号中的行隐式的连接起来 , 你可以利用这个特点. 如果需要, 你可以在表达式外围增加一对额外的圆括号.

NO:query_sql = "SELECT image_id, image_o, image_width, image_height "\ "FROM active_image_tbl "\ "WHERE auction_id=:auction_id AND status=1 " \ "ORDER BY image_id DESC" YES: agent_sql = ("CREATE TABLE IF NOT EXISTS db_agent (" "id INTEGER PRIMARY KEY AUTOINCREMENT, " "device_id VARCHAR(128) DEFAULT '', " "status INTEGER DEFAULT 1, " "updated_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, " "created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP)")

在注释中，如果必要，将长的URL放在一行上。Yes: # See details at# 你应该要么垂直对齐换行的元素, 或者使用4空格的悬挂式缩进(这时第一行不应该有参数):

# 垂直对齐换行的元素foo = long_function_name(var_one, var_two, var_three, var_four)# 4空格的悬挂式缩进(这时第一行不应该有参数)foo = long_function_name( var_one, var_two, var_three, var_four)

空格

括号内不要有空格

YES:spam(ham[1], {eggs: 2}, []) # 注意标点两边的空格NO:spam( ham[ 1 ], { eggs: 2 }, [ ] )

不要在逗号，分号，冒号前面加空格，而应该在它们的后面加

YES:if x == 4: print x, yx, y = y, x NO:if x == 4 : print x , yx , y = y , x

二元操作符两边都要加上一个空格（=， ==，<, >, !=, in, not ...）当’=’用于指示关键字参数或默认参数值时

def complex(real, imag=0.0): return magic(r=real, i=imag)

不要用空格来垂直对齐多行间的标记, 因为这会成为维护的负担(适用于:, #, =等)

YES:foo = 1000 # commentlong_name = 2 # comment that should not be alignedNO:foo = 1000 # commentlong_name = 2 # comment that should not be aligned

模块导入

每个导入应该独占一行

YES:import osimport sysfrom subprocess import Popen, PIPE # PEP8NO:import sys, os

模块导入顺序

标注库导入第三方库导入应用程序指定导入

每种分组中, 应该根据每个模块的完整包路径按字典序排序, 忽略大小写.

import foofrom foo import barfrom foo.bar import bazfrom foo.bar import Quuxfrom Foob import ar

TODO注释

TODO注释应该在所有开头处包含”TODO”字符串, 紧跟着是用括号括起来的你的名字, email地址或其它标识符. 然后是一个可选的冒号. 接着必须有一行注释, 解释要做什么如果你的TODO是”将来做某事”的形式, 那么请确保你包含了一个指定的日期(“2009年11月解决”)或者一个特定的事件

# TODO(kl@gmail.com): Use a "*" here for string repetition.# TODO(Zeke) Change this to use relations.

二元运算符换行(PEP8)

# 不推荐: 操作符离操作数太远income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest) # 推荐：运算符和操作数很容易进行匹配income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)

其它规范

不要在行尾加分号, 也不要用分号将两条命令放在同一行.除非是用于实现行连接, 否则不要在返回语句或条件语句中使用括号. 不过在元组两边使用括号是可以的.顶级定义之间空两行, 方法定义之间空一行

Pandas使用规范

pandas数据结构命名 df_、se_df取一列，禁止使用​​df.列名​​​，可以使用​​df['列名']​​​, 建议使用​​df.loc[:, '列名']​​禁止使用​​df.ix​​

目录结构示例

|--docs|--requests| |--__init__.py| |--_internal_utils.py| |--utils.py| |--api.py|--tests|--setup.py|--README.rst|--LICENSE

Class结构示例

# -*- coding: utf-8 -*-# (C) JiaaoCap, Inc. 2017-2018# All rights reserved# Licensed under Simplified BSD License (see LICENSE)"""requests.apiThis module contains xxx. This module is designed to xxx."""# stdlibimport osimport timefrom base64 import b64encode# 3ptry: import psutilexception ImportError: psutil = Noneimport simplejson as json# projectfrom .utils import current_timefrom ._internal_utils import internal_funcclass Response(object): """A user-created :class:`Response ` object. Used to xxx a :class: `JsonResponse `, which is xxx :param data: response data :param file: response files Usage:: >>> import api >>> rep = api.Response(url=" """ def __init__(self, data, files, json, url) self.data = data @staticmethod def _sort_params(params): """This is a private static method""" return params def to_json(): """The fully method blala bian shen, xxx sent to the server. Usage:: >>> import api >>> rep = api.Response(url=" >>> rep.to_json() """ if self.url == " return True return False

相关链接

Google开源项目风格指南:​​8 -- Style Guide for Python Code:​​PEP8 编码规范中文版​

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。