技术背景

编码规范是所有编程语言都有可能面临的问题，严格的按照编码规范来写代码，不仅能够提高代码的可读性，在后续程序的可维护性上面也有较大的帮助。尤其是在开源项目中，一个具备良好编程规范的项目往往能够吸引更多的开发者一起贡献。这里我们介绍2款可以自动帮助我们进行代码格式化规范的工具：autopep8以及black的安装和基本使用方法。

autopep8的安装

因为都是python写的规范工具，可以用pip来直接进行版本管理和安装：

[dechin@dechin-manjaro autopep8]$ python3 -m pip install autopep8

Requirement already satisfied: autopep8 in /home/dechin/anaconda3/lib/python3.8/site-packages (1.5.4)

Requirement already satisfied: toml in /home/dechin/anaconda3/lib/python3.8/site-packages (from autopep8) (0.10.1)

Requirement already satisfied: pycodestyle>=2.6.0 in /home/dechin/anaconda3/lib/python3.8/site-packages (from autopep8) (2.6.0)

安装完成后，可以使用如下指令测试是否安装成功：

[dechin@dechin-manjaro autopep8]$ autopep8 --help

usage: autopep8 [-h] [--version] [-v] [-d] [-i] [--global-config filename]

                [--ignore-local-config] [-r] [-j n] [-p n] [-a] [--experimental]

                [--exclude globs] [--list-fixes] [--ignore errors] [--select errors]

                [--max-line-length n] [--line-range line line] [--hang-closing]

                [--exit-code]

                [files [files ...]]

Automatically formats Python code to conform to the PEP 8 style guide.

positional arguments:

  files                 files to format or '-' for standard in

optional arguments:

  -h, --help            show this help message and exit

  --version             show program's version number and exit

  -v, --verbose         print verbose messages; multiple -v result in more verbose messages

  -d, --diff            print the diff for the fixed source

  -i, --in-place        make changes to files in place

  --global-config filename

                        path to a global pep8 config file; if this file does not exist then

                        this is ignored (default: /home/dechin/.config/pep8)

  --ignore-local-config

                        don't look for and apply local config files; if not passed,

                        defaults are updated with any config files in the project's root

                        directory

  -r, --recursive       run recursively over directories; must be used with --in-place or

                        --diff

  -j n, --jobs n        number of parallel jobs; match CPU count if value is less than 1

  -p n, --pep8-passes n

                        maximum number of additional pep8 passes (default: infinite)

  -a, --aggressive      enable non-whitespace changes; multiple -a result in more

                        aggressive changes

  --experimental        enable experimental fixes

  --exclude globs       exclude file/directory names that match these comma-separated globs

  --list-fixes          list codes for fixes; used by --ignore and --select

  --ignore errors       do not fix these errors/warnings (default: E226,E24,W50,W690)

  --select errors       fix only these errors/warnings (e.g. E4,W)

  --max-line-length n   set maximum allowed line length (default: 79)

  --line-range line line, --range line line

                        only fix errors found within this inclusive range of line numbers

                        (e.g. 1 99); line numbers are indexed at 1

  --hang-closing        hang-closing option passed to pycodestyle

  --exit-code           change to behavior of exit code. default behavior of return value,

                        0 is no differences, 1 is error exit. return 2 when add this

                        option. 2 is exists differences.

这些弹出的内容，同时也是autopep8的使用框架。

autopep8使用示例

这里我们使用一个官方提供的案例来进行测试，首先我们看一段非常杂乱的python代码，这串代码显然是不符合python编码规范的：

# example1.py

import math, sys;

def example1():

    ####This is a long comment. This should be wrapped to fit within 72 characters.

    some_tuple=(   1,2, 3,'a'  );

    some_variable={'long':'Long code lines should be wrapped within 79 characters.',

    'other':[math.pi, 100,200,300,9876543210,'This is a long string that goes on'],

    'more':{'inner':'This whole logical line should be wrapped.',some_tuple:[1,

    20,300,40000,500000000,60000000000000000]}}

    return (some_tuple, some_variable)

def example2(): return {'has_key() is deprecated':True}.has_key({'f':2}.has_key(''));

class Example3(   object ):

    def __init__    ( self, bar ):

     #Comments should have a space after the hash.

     if bar : bar+=1;  bar=bar* bar   ; return bar

     else:

                    some_string = """

                       Indentation in multiline strings should not be touched.

Only actual code should be reindented.

"""

                    return (sys.path, some_string)

其中各种函数都被堆到一起，虽然代码也能够正确的运行，但是让人看了阅读起来实在是非常费劲，于是我们可以用autopep8这个工具来进行格式化处理：

[dechin@dechin-manjaro autopep8]$ autopep8 --in-place --aggressive --aggressive example1.py

运行完上述指令后，我们再来看看刚才的代码文件：

# example1.py

import math

import sys

def example1():

    # This is a long comment. This should be wrapped to fit within 72

    # characters.

    some_tuple = (1, 2, 3, 'a')

    some_variable = {

        'long': 'Long code lines should be wrapped within 79 characters.',

        'other': [

            math.pi,

            100,

            200,

            300,

            9876543210,

            'This is a long string that goes on'],

        'more': {

            'inner': 'This whole logical line should be wrapped.',

            some_tuple: [

                1,

                20,

                300,

                40000,

                500000000,

                60000000000000000]}}

    return (some_tuple, some_variable)

def example2(): return ('' in {'f': 2}) in {'has_key() is deprecated': True}

class Example3(object):

    def __init__(self, bar):

        # Comments should have a space after the hash.

        if bar:

            bar += 1

            bar = bar * bar

            return bar

        else:

            some_string = """

                       Indentation in multiline strings should not be touched.

Only actual code should be reindented.

"""

            return (sys.path, some_string)

可以看到的是，原本代码中存在的几个问题，比如换行、导包、注释等，都被格式化的处理了，这样一行非常简单的指令，可以帮助我们节约大量的时间。

autopep8不能解决的问题

其实autopep8也并不能一次性解决所有的PEP8规范中的问题，比如以下的一个案例：

[dechin@dechin-manjaro autopep8]$ cat example2.py

# example2.py

print ("sjalfjlsa kkajslajs ls dlaj la jsk dka jdla kjdlksa jd alsk jdlka jsdlak jlksa jla dasajdk la jk das dada sa.")

(base) [dechin@dechin-manjaro autopep8]$ autopep8 --in-place -a -a example2.py

(base) [dechin@dechin-manjaro autopep8]$ cat example2.py

# example2.py

print("sjalfjlsa kkajslajs ls dlaj la jsk dka jdla kjdlksa jd alsk jdlka jsdlak jlksa jla dasajdk la jk das dada sa.")

在这个案例中，我们给出了一个代码行长度超过规范要求的例子，但是用autopep8处理之后，代码并没有被改变，如果此时用flake8来进行检测，还是能够检查出代码超长的问题：

[dechin@dechin-manjaro autopep8]$ flake8

./example2.py:4:80: E501 line too long (115 > 79 characters)

因此这些自动规范化处理的工具毕竟是机器处理，要想真正的达到规范要求，我们最好还是自动规范化的工具结合规范检查的工具，再配合人工的修改，这样才能够写出质量更高的代码。

black工具的安装

除了autopep8之外，还有另外一款也非常常用的自动化规范工具：black，这里我们就不展开介绍其使用方法，仅介绍安装的过程及其官方的帮助文档：

[dechin@dechin-manjaro autopep8]$ python3 -m pip install black -i https://mirrors.cloud.tencent.com/pypi/simple

Looking in indexes: https://mirrors.cloud.tencent.com/pypi/simple

Collecting black

  Downloading https://mirrors.cloud.tencent.com/pypi/packages/dc/7b/5a6bbe89de849f28d7c109f5ea87b65afa5124ad615f3419e71beb29dc96/black-20.8b1.tar.gz (1.1 MB)

     |████████████████████████████████| 1.1 MB 724 kB/s

  Installing build dependencies ... done

  Getting requirements to build wheel ... done

    Preparing wheel metadata ... done

Requirement already satisfied: regex>=2020.1.8 in /home/dechin/anaconda3/lib/python3.8/site-packages (from black) (2020.10.15)

Requirement already satisfied: typing-extensions>=3.7.4 in /home/dechin/anaconda3/lib/python3.8/site-packages (from black) (3.7.4.3)

Requirement already satisfied: click>=7.1.2 in /home/dechin/anaconda3/lib/python3.8/site-packages (from black) (7.1.2)

Collecting pathspec<1,>=0.6

  Downloading https://mirrors.cloud.tencent.com/pypi/packages/29/29/a465741a3d97ea3c17d21eaad4c64205428bde56742360876c4391f930d4/pathspec-0.8.1-py2.py3-none-any.whl (28 kB)

Collecting typed-ast>=1.4.0

  Downloading https://mirrors.cloud.tencent.com/pypi/packages/0d/14/d54fd856673e3a5cb230e481bcdea04976c28b691a65029a7d45aef80575/typed_ast-1.4.3-cp38-cp38-manylinux1_x86_64.whl (774 kB)

     |████████████████████████████████| 774 kB 939 kB/s

Requirement already satisfied: toml>=0.10.1 in /home/dechin/anaconda3/lib/python3.8/site-packages (from black) (0.10.1)

Collecting mypy-extensions>=0.4.3

  Downloading https://mirrors.cloud.tencent.com/pypi/packages/5c/eb/975c7c080f3223a5cdaff09612f3a5221e4ba534f7039db34c35d95fa6a5/mypy_extensions-0.4.3-py2.py3-none-any.whl (4.5 kB)

Requirement already satisfied: appdirs in /home/dechin/anaconda3/lib/python3.8/site-packages (from black) (1.4.4)

Building wheels for collected packages: black

  Building wheel for black (PEP 517) ... done

  Created wheel for black: filename=black-20.8b1-py3-none-any.whl size=124184 sha256=2a1cde43fd729754692b801426aa8cd0becaabe73ae989f6caa761bac46ca9de

  Stored in directory: /home/dechin/.cache/pip/wheels/b5/b8/0f/2d0f8b6f216e8a42f90dcc4d960f30dbf8d5e08dc1b034b32c

Successfully built black

Installing collected packages: pathspec, typed-ast, mypy-extensions, black

Successfully installed black-20.8b1 mypy-extensions-0.4.3 pathspec-0.8.1 typed-ast-1.4.3

同样的也是使用pip来进行包的安装和管理，然后可以在命令行运行black --help查看帮助文档，整体而言跟autopep8还是非常类似的。

[dechin@dechin-manjaro autopep8]$ black --help

Usage: black [OPTIONS] [SRC]...

  The uncompromising code formatter.

Options:

  -c, --code TEXT                 Format the code passed in as a string.

  -l, --line-length INTEGER       How many characters per line to allow.

                                  [default: 88]

  -t, --target-version [py27|py33|py34|py35|py36|py37|py38]

                                  Python versions that should be supported by

                                  Black's output. [default: per-file auto-

                                  detection]

  --pyi                           Format all input files like typing stubs

                                  regardless of file extension (useful when

                                  piping source on standard input).

  -S, --skip-string-normalization

                                  Don't normalize string quotes or prefixes.

  --check                         Don't write the files back, just return the

                                  status.  Return code 0 means nothing would

                                  change.  Return code 1 means some files

                                  would be reformatted. Return code 123 means

                                  there was an internal error.

  --diff                          Don't write the files back, just output a

                                  diff for each file on stdout.

  --color / --no-color            Show colored diff. Only applies when

                                  `--diff` is given.

  --fast / --safe                 If --fast given, skip temporary sanity

                                  checks. [default: --safe]

  --include TEXT                  A regular expression that matches files and

                                  directories that should be included on

                                  recursive searches.  An empty value means

                                  all files are included regardless of the

                                  name.  Use forward slashes for directories

                                  on all platforms (Windows, too).  Exclusions

                                  are calculated first, inclusions later.

                                  [default: \.pyi?$]

  --exclude TEXT                  A regular expression that matches files and

                                  directories that should be excluded on

                                  recursive searches.  An empty value means no

                                  paths are excluded. Use forward slashes for

                                  directories on all platforms (Windows, too).

                                  Exclusions are calculated first, inclusions

                                  later.  [default: /(\.direnv|\.eggs|\.git|\.

                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu

                                  ild|buck-out|build|dist)/]

  --force-exclude TEXT            Like --exclude, but files and directories

                                  matching this regex will be excluded even

                                  when they are passed explicitly as arguments

  -q, --quiet                     Don't emit non-error messages to stderr.

                                  Errors are still emitted; silence those with

                                  2>/dev/null.

  -v, --verbose                   Also emit messages to stderr about files

                                  that were not changed or were ignored due to

                                  --exclude=.

  --version                       Show the version and exit.

  --config FILE                   Read configuration from FILE path.

  -h, --help                      Show this message and exit.

总结概要

本文主要通过介绍两个python中常用的编码规范格式化工具：autopep8和black来讲解python编程中一些快速处理编程规范问题的方法，同时也说明了这些软件的局限性。编程规范也是人为制定的，事实上在实际项目中，也不是所有的编程规范都需要满足，这就需要项目的组织者或者领导者有自己的基本判断。结合代码规范检查工具flake8以及文章中介绍的这些代码规范格式化工具，最重要的还是要配合以人的判断和调整，才能使得项目具有更好的可读性、可维护性以及更友善的生态。

版权声明

本文首发链接为：https://www.cnblogs.com/dechinphy/p/formater.html

作者ID：DechinPhy

更多原著文章请参考：https://www.cnblogs.com/dechinphy/

打赏专用链接：https://www.cnblogs.com/dechinphy/gallery/image/379634.html

腾讯云专栏同步：https://cloud.tencent.com/developer/column/91958

参考链接

1. https://blog.csdn.net/yjk13703623757/article/details/88793137