pysen

安装

PyPI

如果您对linter版本没有偏好（推荐新手使用）

pip install "pysen[lint]"

使用您选择的linter版本安装pysen

pip install pysen
pip install black==21.10b0 flake8==4.0.1 isort==5.10.1 mypy==0.910

其他安装示例

# pipenv
pipenv install --dev "pysen[lint]==0.11.0"
# poetry
poetry add -D pysen==0.11.0 -E lint

快速入门：使用pysen设置代码检查器

将以下pysen配置放入你的Python包的pysen.toml或pyproject.toml中

[tool.pysen]
version = "0.11"

[tool.pysen.lint]
enable_black = true
enable_flake8 = true
enable_isort = true
enable_mypy = true
mypy_preset = "strict"
line_length = 88
py_version = "py38"
[[tool.pysen.lint.mypy_targets]]
  paths = ["."]

然后，执行以下命令

$ pysen run lint
$ pysen run format  # corrects errors with compatible commands (black, isort)

完成！pysen，或者更准确地说，支持指定代码检查器的pysen任务，将为black、isort、mypy和flake8生成配置文件，并使用适当的配置运行它们。有关可以在配置文件中编写的配置项的详细信息，请参阅pysen/pyproject_model.py。

你还可以通过在你的Python包的setup.py中添加以下行来添加自定义设置命令

import pysen
setup = pysen.setup_from_pyproject(__file__)

$ python setup.py lint

我们还提供了一个Python接口来自定义我们的配置并扩展pysen。有关详细信息，请参阅以下两个示例

• Python配置示例：examples/advanced_example/config.py
• pysen插件示例：examples/plugin_example/plugin.py

常见问题解答

Q. 如何使用mypy >= 0.800？
A. 请参阅使用你选择的代码检查器版本安装pysen

Q. mypy报告了错误源文件在两个不同的模块名称下重复。
A. 添加tool.pysen.lint.mypy_targets部分，确保每个部分中的文件名都是唯一的。

Q. 如何更改代码检查器X的特定设置？
A. 我们优先考虑惯例而非配置。然而，你总是可以创建自己的插件。请参阅：创建插件来自定义pysen

Q. pysen似乎忽略了某些文件。
A. pysen仅检查git中跟踪的文件。尝试将文件添加到git add。你也可以通过设置环境变量PYSEN_IGNORE_GIT=1来禁用此行为。

Q. 如何只运行[flake8|black|isort|mypy]？
A. 尝试使用--enable和--disable选项，例如，pysen --enable flake --enable black run lint。

Q. 没有文件名的文件不会被检查。
A. 在tool.pysen.lint.source中的include部分显式添加这些文件。

Q. 我如何向我的pyproject.toml添加额外的设置，例如，pydantic-mypy？
A. 在[tool.pysen-cli]部分下添加settings_dir="."。

什么是pysen？

pysen旨在提供一个统一的平台来配置和运行日常开发工具。我们设想以下未来场景

• 你打开任何项目并运行pysen run lint、pysen run format将检查和格式化整个代码库
• 使用单行配置文件设置标准编码风格

pysen集中了团队积累的开发工具相关的代码和知识，特别是针对Python代码检查器。你可以创建可以从setup.py和我们的命令行工具中执行的任务。我们目前提供以下工具的设置文件管理任务

• 代码检查器
  • flake8
  • isort
  • mypy
  • black
• 工具
  • （计划中）protoc

pysen不是什么？

• pysen本身不是一个代码检查工具。相反，pysen run lint通过从pysen的更抽象设置自动设置它们的配置来协调多个Python代码检查工具。
• pysen不管理你的依赖项和包。我们建议使用包管理器，如pipenv或poetry来锁定依赖项版本，包括pysen协调整的代码检查工具的版本（即isort、mypy、flake8、black）。这些工具的确认版本可以在pysen的extra_requires/lint部分找到，尽管可能更高版本也可以工作。你不应该依靠pip install pysen[lint]来控制代码检查工具的版本。
• pysen不仅限于代码检查用途或Python。请参阅插件部分以获取详细信息。

工作原理：设置文件目录

在内部，每次运行pysen时，它都会生成设置文件作为临时文件，以便供linters使用。您可能希望将这些设置文件保留在您的磁盘上，例如，当您想使用它们进行编辑时。如果是这种情况，请运行以下命令以生成所需目录的设置文件：

$ pysen generate [out_dir]

您可以在执行pysen run时指定pysen使用的设置目录。为此，请将以下部分添加到您的配置文件中：

[tool.pysen-cli]
settings_dir = "path/to/generate/settings"

当您指定一个已包含一些配置的目录时，pysen会合并其内容。结果的行为可能与您未指定settings_dir时不同。

请注意，此选项仅在您通过其CLI使用pysen时才受尊重。当使用pre-commit或setuptools时，您需要将settings_dir作为参数指定。

提示：IDE/文本编辑器集成

vim

您可以通过以下方式将pysen报告的错误添加到您的quickfix窗口：

:cex system("pysen run_files lint --error-format gnu ".expand('%:p'))

另一种方法是将pysen设置为makeprg

set makeprg=pysen\ run_files\ --error-format\ gnu\ lint\ %

然后运行:make将在您的quickfix窗口中填充错误。这也适用于vim-dispatch，只要您调用:Make而不是:Dispatch（出于此原因）

结果将如下所示：

还有一个第三方插件可用。

• pysen.vim

Emacs

请参阅编译模式。以下是一个用于Python的示例钩子。

(add-hook 'python-mode-hook
    (lambda ()
        (set (make-local-variable 'compile-command)
            (concat "pysen run_files lint --error-format gnu  " buffer-file-name))))

VSCode

有一个第三方插件可用。

请注意，如果您已通过VSCode Python扩展直接配置了如flake8之类的linters，则可能会报告重复的错误。

配置pysen

我们提供了两种为pysen编写配置的方法。

一种是配置文件中的[tool.pysen.lint]部分。这是配置pysen最简单的方法，但我们提供的设置有限。

另一种方法是编写一个直接配置pysen的Python脚本。如果您想自定义pysen生成的配置文件、pysen接受的命令行参数或pysen执行的任何操作，我们建议您使用此方法。有关更多示例，请参阅pysen/examples。

配置模型

请参阅pysen/pyproject_model.py以获取最新模型。

以下是一个基本配置示例：

[tool.pysen]
version = "0.11"

[tool.pysen.lint]
enable_black = true
enable_flake8 = true
enable_isort = true
enable_mypy = true
mypy_preset = "strict"
line_length = 88
py_version = "py38"
isort_known_third_party = ["numpy"]
isort_known_first_party = ["pysen"]
mypy_ignore_packages = ["pysen.generated.*"]
mypy_path = ["stubs"]
[[tool.pysen.lint.mypy_targets]]
  paths = [".", "tests/"]

[tool.pysen.lint.source]
  includes = ["."]
  include_globs = ["**/*.template"]
  excludes = ["third_party/"]
  exclude_globs = ["**/*_grpc.py"]

[tool.pysen.lint.mypy_modules."pysen.scripts"]
  preset = "entry"

[tool.pysen.lint.mypy_modules."numpy"]
  ignore_errors = true

pysen将按照以下顺序查找配置文件：

1. 带有tool.pysen部分的pysen.toml
2. 带有tool.pysen部分的pyproject.toml

创建一个插件来自定义pysen

我们提供了一个插件接口，用于自定义我们的工具支持、设置文件管理、设置命令等。有关更多详细信息，请参阅pysen/examples/plugin_example。

开发

需要pipenv来管理我们的开发环境。

# setup your environment
$ pipenv sync
# activate the environment
$ pipenv shell

• 更新Pipfile.lock中的依赖项

$ pipenv lock --pre

• 运行所有测试

$ pipenv run tox

mypy预设

mypy预设strict旨在使以下包的开发者生活更轻松

• OpenCV
• PyTorch
• scikit-learn

我们建议开发者减轻very strict预设中的某些规则，以避免一些麻烦。如果您使用这些包与strict预设，并且仍然不方便，请告诉我们。

贡献

我们的主要优先级是满足Preferred Networks内部项目的要求。因此，我们必须评估每个功能/拉取请求是否有利于我们的项目。原则上，我们对以下此类小事情持开放态度

• 报告错误的issue
• 修复错别字或小错误的少量PR

关于新功能或主要功能增强，核心开发者将根据每个案例确定所提议的想法是否符合pysen的目标和概念。如有疑问，请先不要犹豫，先打开一个问题。