Pyink，发音为 pī-ˈiŋk，是一个Python格式化工具，从 Black 分支出来，具有一些不同的格式化行为。我们打算继续基于Black的最新更改进行重基。

为什么选择 Pyink？

我们非常希望采用 Black，但一夜之间对在单一代码库中工作的数千名开发者来说影响太大。我们还有其他假设特定格式的 Python 工具，一次性更新它们将是一项庞大的任务。我们决定作为中期解决方案，维护一些针对 Black 的本地补丁，并将其作为一个名为 Pyink 的独立工具发布。

Pyink 旨在作为采用助手，我们希望在未来删除尽可能多的补丁。

主要区别是什么？

• 支持两个空格缩进，使用 pyink-indentation 选项。

• 使用 pyink-use-majority-quotes 选项，通过计算文件中的大多数来推断首选引号样式。

• 如果行超出长度仅因为 pragmas，则不会换行尾部的注释（参见 psf/black#2843）。示例

  # Pyink:
  result = some_other_module._private_function(arg="value")  # pylint: disable=protected-access
  
  # Black:
  result = some_other_module._private_function(
      arg="value"
  )  # pylint: disable=protected-access
  

• 不要将导入括在括号中并将它们移到单独的行（参见 psf/black#3324）。示例

  # Pyink:
  from very_long_top_level_package_name.sub_package.another_level import a_long_module
  
  # Black:
  from very_long_top_level_package_name.sub_package.another_level import (
      a_long_module,
  )
  

• 在无 docstrings 的类语句和第一个方法之间添加一个空行。我们预计我们将在某个时刻简单地从 Pyink 中移除这个差异。示例

  # Pyink:
  class MyTest(unittest.TestCase):
  
      def test_magic(self):
          ...
  
  # Black:
  class MyTest(unittest.TestCase):
      def test_magic(self):
          ...
  

• 模块 docstrings 的格式与其他 docstrings 相同（参见 psf/black#3493）。

• 如果内容不适合单行，则保留字符串周围的现有括号。这与 https://github.com/psf/black/pull/3640 相关，我们仍然希望在使用隐式连接字符串时保留括号，使其更明显地是一个单一函数参数。示例

  # Original code:
  func1(
      (
          " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
          " incididunt ut labore et dolore magna aliqua Ut enim ad minim"
      ),
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
  )
  
  func2(
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
      " incididunt ut labore et dolore magna aliqua Ut enim ad minim",
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
  )
  
  # Pyink:
  func1(
      (
          " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
          " incididunt ut labore et dolore magna aliqua Ut enim ad minim"
      ),
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
  )
  
  func2(
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
      " incididunt ut labore et dolore magna aliqua Ut enim ad minim",
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
  )
  
  # Black:
  func1(
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
      " incididunt ut labore et dolore magna aliqua Ut enim ad minim",
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
  )
  
  func2(
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
      " incididunt ut labore et dolore magna aliqua Ut enim ad minim",
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
  )
  

• 暂时禁用以下 Black 未来样式更改

  • https://github.com/psf/black/pull/2916
  • https://github.com/psf/black/pull/2278
  • https://github.com/psf/black/pull/4146

历史差异

这些是过去存在的差异。我们已经将它们上传到 Black，因此它们现在是一致的。

• 将连接的字符串括在括号中作为函数参数（参见 psf/black#3292）。示例

  # New:
  function_call(
      (
          " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
          " incididunt ut labore et dolore magna aliqua Ut enim ad minim"
      ),
      " veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo",
  )
  
  # Old:
  function_call(
      " lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
      " incididunt ut labore et dolore magna aliqua Ut enim ad minim",
      " veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo",
  )
  

• 首选分割赋值语句的右侧（参见 psf/black#1498）。示例

  # New:
  some_dictionary["some_key"] = (
      some_long_expression_causing_long_line
  )
  
  # Old:
  some_dictionary[
      "some_key"
  ] = some_long_expression_causing_long_line
  

• 首选不打破立即嵌套的大括号之间的行（参见 psf/black#1811）。示例

  # Pyink:
  secrets = frozenset({
      1001,
      1002,
      1003,
      1004,
      1005,
      1006,
      1007,
      1008,
      1009,
  })
  
  # Black:
  secrets = frozenset(
      {
          1001,
          1002,
          1003,
          1004,
          1005,
          1006,
          1007,
          1008,
          1009,
      }
  )
  

• 使用 --pyink-lines= 参数仅格式化选定的行范围（参见 psf/black#830）。

如何使用 Pyink？

与 black 相同，但您将使用 pyink。所有 black 命令行选项都由 pyink 支持。要配置 pyproject.toml 文件中的选项，您需要将它们放在 [tool.pyink] 部分而不是 [tool.black] 部分。

还有一些仅适用于 Pyink 的选项

  --pyink / --no-pyink            Enable the Pyink formatting mode. Disabling
                                  it should behave the same as Black.
                                  [default: pyink]
  --pyink-indentation [2|4]       The number of spaces used for indentation.
                                  [default: 4]
  --pyink-use-majority-quotes     When normalizing string quotes, infer
                                  preferred quote style by calculating the
                                  majority in the file. Multi-line strings and
                                  docstrings are excluded from this as they
                                  always use double quotes.

有 Pyink 的 VS Code 扩展吗？

没有，但通过一点技巧，您可以使用 Black Formatter 扩展。安装 Pyink 和扩展后，您可以在 VS Code 的 settings.json 中设置这些。

{
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter"
    },
    "black-formatter.path": [
        "path/to/pyink"
    ]
}

我可以使用 Pyink 与 pre-commit 框架一起使用吗？

是的！您可以在您的 .pre-commit-config.yaml 文件中放置以下内容

repos:
  - repo: https://github.com/google/pyink
    rev: 23.3.0
    hooks:
      - id: pyink
        # It is recommended to specify the latest version of Python
        # supported by your project here, or alternatively use
        # pre-commit's default_language_version, see
        # https://pre-commit.git-scm.cn/#top_level-default_language_version
        language_version: python3.9

为什么叫这个名字？

我们希望有一个与 Black 具有相同字符数的名字，以便更容易打补丁。而且乌贼墨是黑色的。

许可证

MIT

贡献

请参阅 贡献指南。

变更日志

请参阅 CHANGES.md。

免责声明

这不是一个官方支持的 Google 产品。