plone.recipe.codeanalysis 3.0.1

介绍

plone.recipe.codeanalysis为基于Buildout的Python项目提供静态代码分析，包括flake8、JSHint、CSS Lint和其他代码检查。

此buildout配方创建一个脚本来运行代码分析

bin/code-analysis

默认情况下，plone.recipe.codeanalysis还会创建一个git预提交钩子，以便在每次提交之前自动运行代码分析。

plone.recipe.codeanalysis附带Jenkins集成，允许在本地机器和Jenkins上使用相同的代码分析设置。

它还可以运行任意文件夹的代码分析

bin/code-analysis src/Products.CMFPlone

安装

只需在buildout.cfg中添加一个代码分析部分

[buildout]
parts += code-analysis

[code-analysis]
recipe = plone.recipe.codeanalysis
directory = ${buildout:directory}/src

目录选项不是必需的。尽管如此，如果您不指定目录，代码分析将检查buildout目录中的所有文件。

此配置对于处理现有包很有帮助。如果您创建了一个新包，您可能希望启用所有检查。此配置看起来像这样

[code-analysis]
recipe = plone.recipe.codeanalysis[recommended]
multiprocessing = True
jenkins = False
directory =
    ${buildout:directory}/src
return-status-codes = True
pre-commit-hook = True
# JS
jshint = True
jshint-bin = ${buildout:bin-directory}/jshint
jshint-suppress-warnings = False
jscs = True
jscs-bin = ${buildout:bin-directory}/jscs
jscs-exclude =
    ${buildout:directory}/dev/bower_components
    ${buildout:directory}/node_modules
# CSS
csslint = True
csslint-bin = ${buildout:bin-directory}/csslint
# ZPT
zptlint = True
zptlint-bin = ${buildout:bin-directory}/zptlint
# Chameleon uses XML (there is no chameleon-lint-bin, it uses lxml)
chameleon-lint = False
# XML (there is no xmllint-bin, it uses lxml)
xmllint = True
# scss-lint
scsslint = True
scsslint-bin = ${buildout:bin-directory}/scss-lint
# TS
tslint = True
tslint-bin = ${buildout:directory}/bin/tslint
tslint-exclude = ${:jscs-exclude}
# Conventions
clean-lines = True
clean-lines-exclude = ${:jscs-exclude}
# dependency-checker
dependencychecker = True
dependencychecker-bin = ${buildout:directory}/bin/dependencychecker
# i18n
find-untranslated = True
i18ndude-bin = ${buildout:bin-directory}/i18ndude
flake8-exclude = bootstrap.py,bootstrap-buildout.py,docs,*.egg,*.cpy,*.vpy,overrides

[node]
recipe = gp.recipe.node
npms = csslint jshint jscs tslint
scripts = csslint jshint jscs tslint

[推荐] 额外

此额外操作启用了大量的flake8插件。它们大多数是针对Plone风格指南的编码部分（特别是Python部分）。

以下是当前安装的额外插件

• flake8-blind-except: 警告关于捕获任何异常，即except:

• flake8-coding: 警告缺少编码头的Python文件

• flake8-debugger: 警告代码中发现的调试语句（如pdb…）

• flake8-deprecated: 警告过时的方法调用

• flake8-isort: 警告未正确排序的导入（请注意，需要额外配置）

• flake8-pep3101: 警告关于旧式格式化，即'format a %s' % string

• flake8-plone-api: 警告可能被plone.api调用替换的代码（请注意，这禁止用于Plone核心包）

• flake8-plone-hasattr: 警告使用hasattr，因为它会引发异常

• flake8-print: 警告使用print

• flake8-quotes: 警告使用双引号（plone风格指南说使用单引号）

• flake8-string-format: 警告字符串格式化中的错误

• flake8-todo: 警告代码中存在TODO、XXX

• flake8-commas: 警告方法调用、列表或字典中的最后一个元素不以逗号结尾

Git钩子

• pre-commit-hook

• pre-commit-return-status-codes

• pre-push-hook

• pre-push-return-status-codes

您可以选择激活gitpre-commit-hook和/或pre-push-hook钩子。您可以通过将return-status-codes设置为‘True’来使这些钩子阻止（中止）。您可以使用pre-commit-return-status-codes和pre-push-return-status-codes分别调整每个钩子的返回代码行为。

最适合您的是口味和代码库的问题。

如果您想确保在每次提交时工作区始终保持干净，并且您希望发现任何异常时中止提交，您可以配置

[code-analysis]
return-status-codes = True
pre-commit-hook = True

如果您在一个大型代码库中工作，解析需要很长时间，并且您的工怍流程是使用许多小提交，那么您可能会对提交前的延迟感到烦恼。或者，也许您喜欢检查您的工作的一部分，同时在您的工怍树中有其他尚未清理的文件。

在这种情况下，您可能希望禁用提交前的检查，并使用阻塞的预推送检查。

[code-analysis]
return-status-codes = True
pre-commit-hook = False
pre-push-hook = True

或者，您可能希望默认情况下运行非阻塞的 code-analysis，以取悦 Jenkins，但仍然希望在提交前和预推送时都有阻塞的检查？可以做到。

[code-analysis]
return-status-codes = False
pre-commit-hook = True
pre-commit-return-status-codes = True
pre-push-hook = True
pre-push-return-status-codes = True

我知道，这是一个假设的例子，但它说明了相关的选项。

配置 覆盖

上述选项配置了项目级别的代码分析。有时开发者可能希望从本地偏离项目级别的设置，例如，即使项目全局设置是在违规时不要中止提交，也要让 git 预提交钩子阻塞违规。

例如，如果项目 buildout.cfg 读取

[code-analysis]
overrides = code-analysis-overrides-acmecorp
return-status-codes = False
pre-commit-hook = True

但是作为一个开发者，我宁愿有一个阻塞的预推送而不是非阻塞的预提交，我可以在我的 .buildout/default.cfg 配置中配置覆盖项如下

[code-analysis-overrides-acmecorp]
return-status-codes = True
pre-commit-hook = False
pre-push-hook = True

这对于让用户自己选择他们是否想要预提交钩子或预推送钩子非常有用，以及他们是否希望阻塞违规（这样他们就不必修改提交）或者他们是否希望非阻塞检查（这样他们可以在提交的文件集之外的工作树中有无效文件）。YMMV。

请注意，如果项目没有在项目级别配置 overrides，您仍然可以在 .buildout/default.cfg 中配置它

[code-analysis]
overrides = code-analysis-overrides

[code-analysis-overrides]
return-status-codes = True

建议为每个项目定义一个覆盖名称，这样开发者就可以根据项目调整他们的覆盖项。仅当存储库确实与典型存储库有很大不同（例如，大得多）时，存储库特定的覆盖名称才有意义。例如，项目覆盖名称将在开发者的 .buildout/default.cfg 中显示如下

[code-analysis-overrides-plone]
return-status-codes = True
pre-commit-hook = True
pre-push-hook = True

[code-analysis-overrides-grok]
<= code-analysis-overrides-plone

[code-analysis-overrides-acmecorp]
return-status-codes = True
pre-commit-hook = False
pre-push-hook = True

对于非常希望不向他们的开发者提供此选项的项目，有在项目 buildout.cfg 中阻塞覆盖的简单解决方案

[code-analysis]
overrides = False

建议您实际上与您的同事讨论哪些覆盖项是不可接受的，而不是采取这种核选项。如果开发者不同意您正在验证的 flake8 扩展集，那实际上是一个社会问题，而不是可以在代码中解决的问题。

控制开发者允许进行的本地重新配置的另一种更微妙的方法是在项目级别配置 overrides-allowed 白名单

[code-analysis]
overrides-allowed = multiprocessing
                    return-status-codes
                    pre-commit-hook
                    pre-commit-return-status-codes
                    pre-push-hook
                    pre-push-return-status-codes

因此，这里列出的覆盖选项将从开发者的本地配置中获取，所有其他选项将从项目 buildout.cfg 中获取。列出空的 overrides-allowed 选项允许覆盖所有选项。

但当然，所有这些都运行在开发者的机器上...

Jenkins安装

plone.recipe.codeanalysis 提供了一个 Jenkins 设置，允许在 Jenkins CI 服务器上运行它，并通过 Jenkins Violations 插件 处理和集成输出。

通常您不希望配方在您的本地机器上创建 Jenkins 输出文件。因此，仅在 CI 机器上启用 Jenkins 输出是有意义的。为此，只需创建一个 jenkins.cfg 文件，该文件扩展并覆盖默认 buildout 文件（包括其他设置）

[buildout]
parts += code-analysis

[code-analysis]
recipe = plone.recipe.codeanalysis
jenkins = True

Jenkins 作业本身应运行 bin/code-analysis

python bootstrap.py -c jenkins.cfg
bin/buildout -c jenkins.cfg
bin/jenkins-test --all
bin/code-analysis

需要配置Jenkins Violations插件以读取此配置生成的输出文件。

pep8（用于读取flake8输出）

**/parts/code-analysis/flake8.log

csslint

**/parts/code-analysis/csslint.xml

csslint

**/parts/code-analysis/scsslint.xml

jslint（用于读取jshint输出）

**/parts/code-analysis/jshint.xml

checkstyle（用于读取jscs输出）

**/parts/code-analysis/jscs.xml

文件系统输出

如果将jenkins设置为False，您仍然可以通过将flake8-filesystem = True设置在文件系统中存储输出。如果jenkins设置为True，则此设置将被忽略。

输出

**/parts/code-analysis/flake8.txt

链接

代码仓库

https://github.com/plone/plone.recipe.codeanalysis

持续集成

https://travis-ci.org/plone/plone.recipe.codeanalysis

问题跟踪器

https://github.com/plone/plone.recipe.codeanalysis/issues

支持选项

如果由于某些原因需要在特定行上绕过检查，您可以在Python中使用# noqa或在JavaScript文件中使用// noqa。这对我们的大多数检查都有效。

该配方支持以下选项

directory

接受代码分析的目录。

return-status-codes

如果设置为True，bin/code-analysis脚本将返回一个错误代码，持续集成服务器（如Travis CI）可以使用此代码根据代码分析输出失败或通过一个任务。请注意，Jenkins通常不需要此选项（此选项最好由Jenkins Violations插件处理）。请注意，此选项对其他代码分析脚本没有影响。默认为False。

请注意，可以通过使用--return-status-codes或--no-return-status-codes命令行选项在命令行中覆盖此选项。

请注意，如果需要，预提交和提交后钩子可以调整以具有不同的状态代码行为，如下所示。

pre-commit-hook

如果设置为True，将安装一个git预提交钩子，在每次提交之前运行代码分析。默认为True。

pre-commit-hook-return-status-codes

如果设置为True，如果运行了预提交钩子，它将在发现违规时中止提交。默认值是return-status-codes配置的值。

pre-push-hook

如果设置为True，将安装一个git预推送钩子，在将代码推送至远程之前运行代码分析。默认为False。

pre-push-hook-return-status-codes

如果设置为True，如果运行了预推送钩子，它将在发现违规时中止推送。默认值是return-status-codes配置的值。

请注意，通常建议将此选项设置为True，这样您就可以避免推送损坏的工作。具体情况具体分析。

multiprocessing

如果设置为True，code-analysis将派生多个进程，并并行运行所有linters。这将在多核系统上显著提高速度，特别是在使用code-analysis作为预提交钩子时。默认为False。

jenkins

如果设置为True，代码分析步骤将写入可由Jenkins Violations插件处理的输出文件。默认为False。

flake8-filesystem

如果设置为True，flake8代码分析步骤将写入一个输出文件。如果jenkins为True，则忽略。默认为False。

flake8

如果设置为True，运行Flake8代码分析。默认为True。

flake8-extensions

Flake8 现在利用 flake8 扩展系统。默认为无。如果 flake8 设置为 False，则此选项将被忽略。以下是一个使用一些扩展的示例来增强功能

[code-analysis]
recipe = plone.recipe.codeanalysis
flake8 = True
flake8-extensions =
    flake8-blind-except
    flake8-coding
    flake8-debugger
    flake8-quotes
    pep8-naming

flake8 设置

Flake8 使用以下文件查找设置

• setup.cfg（推荐用于 Plone）

• tox.ini

• .flake8

[flake8]
exclude = bootstrap.py,boostrap-buildout.py,docs,*.egg
max-complexity = 10
max-line-length = 79

查看 Flake8 文档

以及它的插件，以查看哪些选项可用。

check-manifest

如果设置为 True，则将运行 check-manifest 来检查您的 MANIFEST.in 文件。默认为 False。

check-manifest-directory

默认为 .，表示检查您在 buildout 中包含代码分析的当前包。

实验性：对于使用多个源包的项目构建，您可能需要输入多个目录或使用 ${buildout:develop} 来包含所有开发包。

dependencychecker

如果设置为 True，则运行导入语句分析并验证与 setup.py 中声明的依赖项。默认为 False。

dependencychecker-bin

设置 dependencychecker 的自定义版本路径。

importchecker

如果设置为 True，则运行导入语句分析并报告未使用的导入。默认为 False。

importchecker-bin

设置 importchecker 的自定义版本路径。

jshint

如果设置为 True，则运行 jshint 代码分析。默认为 False。请注意，plone.recipe.codeanalysis 需要 jshint >= 1.0。

jshint-bin

JSHint 可执行文件。默认为 jshint。如果您已在系统路径中安装 JSHint，则无需执行任何操作。要在 buildout 中安装 JSHint，请使用以下命令

[jshint]
recipe = gp.recipe.node
npms = jshint
scripts = jshint

将 jshint-bin 设置为 ${buildout:bin-directory}/jshint。

jshint-exclude

允许您指定不希望进行代码检查的目录。默认为无。如果要让 JSHint 跳过某些文件，可以在名为 .jshintignore 的文件中列出它们。有关详细信息，请参阅 JSHint 文档。

jshint-suppress-warnings

默认情况下，jshint 的警告将被抑制且不会显示。您可以通过将其设置为 False 来禁用此功能，默认为 True，这是为了向后兼容的原因。

jscs

如果设置为 True，则运行 jscs 代码分析。默认为 False。

JavaScript 代码风格选项应使用 .jscs.json 文件进行配置。您应该使您的 JavaScript 代码与 Plone 的下一代 JavaScript 框架 Mockup 保持一致，并使用以下可用的 .jscs.json 文件：https://github.com/plone/mockup/blob/master/mockup/.jscs.json

所有配置选项均在 jscs 网站 上有文档说明。

jscs-bin

设置 JSCS 的自定义版本路径，例如 /usr/local/bin/jscs。

如果您已在系统路径中安装了 Javascript 代码风格检查器，则无需执行任何操作。要使用 Buildout 安装，请向您的 buildout 添加以下部分，并将 jscs-bin 设置为 {buildout:bin-directory}/jscs

[jscs]
recipe = gp.recipe.node
npms = jscs
scripts = jscs

jscs-exclude

允许您指定不需要检查的目录和/或文件。默认为无。注意，这些目录必须以绝对路径给出，例如使用 ${buildout:directory}/foo/bar/static/js-3rd-party。

csslint

如果设置为True，将运行CSS Lint代码分析。默认为 False。

应该使用 .csslintrc 文件来配置CSS Lint选项。一个典型的 .csslintrc 文件如下所示

--format=compact
--quiet
--ignore=adjoining-classes,floats,font-faces,font-sizes,ids,qualified-headings,unique-headings
--exclude-list=foo/bar/static/third-party.css

此典型配置包括一个列表，其中包含将被视为无用的CSS规则，将被忽略。

请参阅 CSS Lint文档 和 CSS Lint命令行界面，以获取规则详细列表和描述。

csslint-bin

设置自定义CSS Lint版本的路径，例如 /usr/local/bin/csslint。

如果您已将CSS Lint安装在系统路径中，您无需做任何事情。要使用Buildout安装CSS Lint，请将以下部分添加到您的buildout中，并将csslint-bin设置为 {buildout:bin-directory}/csslint

[csslint]
recipe = gp.recipe.node
npms = csslint
scripts = csslint

csslint-exclude

允许您指定不需要检查的目录和/或文件。默认为无。

chameleon-lint

如果设置为True，将运行ChameleonLint代码分析。默认为 False。

ChameleonLint使用 lxml 进行XML解析。没有 chameleon-lint-bin。

请注意，您可能希望激活 chameleon-lint 或 zpt-lint 中的一个，而不是两个，因为它们将应用于同一组文件扩展名（.pt，.cpt，.zpt）。zpt-lint 解析器使用实际的TAL表达式引擎来验证模板，并且通常会在Chameleon扩展上崩溃。另一方面，chameleon-lint 解析器基本上只是检查模板是否是有效的XML。

xmllint

如果设置为True，将运行XMLLint代码分析。默认为 False。

XMLLint使用 lxml 进行XML解析。没有 xmllint-bin。

clean-lines

如果设置为True，任何包含行尾空格或制表的文件将引起警告。默认为 False。

clean-lines-exclude

允许您指定不需要检查的目录和/或文件。默认为无。

[rubygems]
recipe = rubygemsrecipe
gems = scss_lint

Please note that due to some buildout weirdness this will break buildout
on the first buildout run; a second buildout run will complete just fine.

TEST_ALL=true bin/test

已知问题

JSHint “ERROR: Unknown option –verbose”

JSHint                [ OK ]
ERROR: Unknown option --verbose

升级 JSHint 到最新版本 (>= 1.0) 以修复此问题，例如。

$ sudo npm install -g jshint

JSHint “ERROR: Unknown option –exclude”

JSHint                [ OK ]
ERROR: Unknown option --exclude

升级 JSHint 到最新版本 (>= 2.1.6) 以修复此问题，例如。

$ sudo npm install -g jshint

Rubygems 痛苦

Installing rubygems.
rubygems: Extracting package to /app/plone.recipe.codeanalysis/parts
ERROR:  While executing gem ... (Errno::EACCES)
Permission denied @ rb_sysopen - /usr/lib/ruby/gems/2.3.0/specifications/default/bundler-1.16.1.gemspec
rubygems: b''
rubygems: Command failed with exit code 1: ['ruby', 'setup.rb', 'all', '--prefix=/app/plone.recipe.codeanalysis/parts/rubygems', '--no-rdoc', '--no-ri']
While:
Installing rubygems.
Error: System error

解决方案：再次运行 buildout。真的。

测试失败

Traceback (most recent call last):
File "/app/plone.recipe.codeanalysis/plone/recipe/codeanalysis/__init__.py", line 18, in <module>
import zc.buildout
ModuleNotFoundError: No module named 'zc.buildout'

这可能是由于 https://github.com/pypa/pip/issues/4695 所致。解决方案：在运行 bin/buildout 之前运行。

bin/easy_install -U zc.buildout==2.11.0

before running bin/buildout。

示例用法

最小 buildout

>>> write('buildout.cfg',
... """
... [buildout]
... parts = code-analysis
...
... [code-analysis]
... recipe = plone.recipe.codeanalysis
... directory = %(directory)s
... """ % {
...     'directory' : '${buildout:directory}/plone/recipe/codeanalysis',
... })

运行 buildout 会给我们一个运行整个代码分析的“code-analysis”脚本

>>> buildout_output_lower = system(buildout).lower()
>>> '/sample-buildout/bin/code-analysis' in buildout_output_lower
True

也可以运行单个代码分析脚本

>>> '/sample-buildout/bin/code-analysis-flake8' in buildout_output_lower
True
>>> '/sample-buildout/bin/code-analysis-jshint' in buildout_output_lower
True

Flake 8 由 buildout 脚本安装，无需在系统上安装它

>>> '/sample-buildout/bin/flake8' in buildout_output_lower
True

提交前钩子

如果我们有一个 git 仓库

>>> import subprocess
>>> subprocess.call(['mkdir', '-p', '.git/hooks'])
0

然后再次运行 buildout

>>> buildout_output_lower = system(buildout).lower()

然后安装 git 预提交钩子

>>> 'installed git pre-commit hook.' in buildout_output_lower
True

贡献者

• Timo Stollenwerk，原始作者

• Gil Forcada

• Héctor Velarde

• Ramiro Batista da Luz

• Daniel Widerin

• Michael Davis

变更历史