使用autopep8自动规范化python3代码

技术背景

编码规范是所有编程语言都有可能面临的问题，严格的按照编码规范来写代码，不仅能够提高代码的可读性，在后续程序的可维护性上面也有较大的帮助。尤其是在开源项目中，一个具备良好编程规范的项目往往能够吸引更多的开发者一起贡献。这里我们介绍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