目录
- 技术背景
- autopep8的安装
- autopep8使用示例
- autopep8不能解决的问题
- black工具的安装
- 总结概要
- 版权声明
- 参考链接
技术背景
编码规范是所有编程语言都有可能面临的问题，严格的按照编码规范来写代码，不仅能够提高代码的可读性，在后续程序的可维护性上面也有较大的帮助。尤其是在开源项目中，一个具备良好编程规范的项目往往能够吸引更多的开发者一起贡献。这里我们介绍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
参考链接
- https://blog.csdn.net/yjk13703623757/article/details/88793137
