Python开发规范(Google风格规范和PEP8规范及各种普适化的Python项目规范)

应当规避

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

命名约定

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

行内注释(PEP8)

行内注释是与代码语句同行的注释

  1. 行内注释和代码至少要有两个空格分隔

  2. 注释由#和一个空格开始

函数/方法

一个函数必须要有文档字符串, 除非它满足以下条件:

  1. 外部不可见
  2. 非常短小
  3. 简单明了

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
def simple_func(method, timeout)
    """Constructs and sends a :class:`Request <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) <timeouts>` tuple.
    :type timeout: float or tuple
    :return: :class:`Response <Response>` object
    :rtype: requests.Response
    
    Usage::
    
      >>> import requests
      >>> req = requests.request('GET', 'http://httpbin.org/get')
      <Response [200]>
    """
1

行长度

  1. 每行不超过80个字符
  2. 不要使用反斜杠连接行
  3. Python会将 圆括号, 中括号和花括号中的行隐式的连接起来 , 你可以利用这个特点. 如果需要, 你可以在表达式外围增加一对额外的圆括号.
1
2
3
4
5
6
7
8
9
10
11
12
13
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)")

Untitled

Untitled

空格

  1. 括号内不要有空格
1
2
3
4
5
YES:
spam(ham[1], {eggs: 2}, [])                 # 注意标点两边的空格

NO:
spam( ham[ 1 ], { eggs: 2 }, [ ] )

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

1
2
3
4
5
6
7
8
9
YES:
if x == 4:
    print x, y
x, y = y, x

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

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

1
2
3
4
5
6
7
YES:
foo = 1000  # comment
long_name = 2  # comment that should not be aligned

NO:
foo       = 1000  # comment
long_name = 2     # comment that should not be aligned

模块导入

  1. 每个导入应该独占一行
1
2
3
4
5
6
7
YES:
import os
import sys
from subprocess import Popen, PIPE      # PEP8

NO:
import sys, os
  1. 模块导入顺序
    1. 标注库导入
    2. 第三方库导入
    3. 应用程序指定导入
  2. 每种分组中, 应该根据每个模块的完整包路径按字典序排序, 忽略大小写.

TODO注释

  1. TODO注释应该在所有开头处包含”TODO”字符串, 紧跟着是用括号括起来的你的名字, email地址或其它标识符. 然后是一个可选的冒号. 接着必须有一行注释, 解释要做什么
  2. 如果你的TODO是”将来做某事”的形式, 那么请确保你包含了一个指定的日期(“2009年11月解决”)或者一个特定的事件
1
2
# TODO(kl@gmail.com): Use a "*" here for string repetition.
# TODO(Zeke) Change this to use relations.

二元运算符换行(PEP8)

1
2
3
4
5
6
7
8
9
10
11
12
13
# 不推荐: 操作符离操作数太远
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)

class示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
# -*- coding: utf-8 -*-
# (C) JiaaoCap, Inc. 2017-2018
# All rights reserved
# Licensed under Simplified BSD License (see LICENSE)

"""
requests.api

This module contains xxx. 
This module is designed to xxx.
"""

# stdlib
import os
import time

from base64 import b64encode

# 3p
try:
    import psutil
exception ImportError:
    psutil = None
import simplejson as json

# project
from .utils import current_time
from ._internal_utils import internal_func

class Response(object):
    """A user-created :class:`Response <Response>` object.
    
    Used to xxx a :class: `JsonResponse <JsonResponse>`, which is xxx
    
    :param data: response data
    :param file: response files
        
    Usage::
    
        >>> import api
        >>> rep = api.Response(url="http://www.baidu.com")
    """
    
    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="http://www.baidu.com")
            >>> rep.to_json()
        """
        
        if self.url == "www":
            return True
        return False

目录示例

1
2
3
4
5
6
7
8
9
10
|--docs
|--requests
|    |--__init__.py
|    |--_internal_utils.py
|    |--utils.py
|    |--api.py
|--tests
|--setup.py
|--README.rst
|--LICENSE

导入模块为什么Pycharm里面可以运行在shell里面无法运行

PythonPath说明：（公司复用python代码）

https://github.com/ydf0509/pythonpathdemo