PyCharm：在区域上运行`black -S`

编程问答 2022-05-28

问题描述

我们还没有准备好使用 black 自动格式化整个源代码。

但有时我想通过 PyCharm 在一个区域上执行 black -S。

有一个 hint in the docs 如何在整个文件上运行 black（或 black -S（我喜欢的））。但是……

如何仅在选定区域上运行黑色？

解决方法

在 PyCharm IDE 中的代码区域上使用 Python Black 可以通过将其实现为 external tool 来完成。目前 Black 有两个主要选项来选择要格式化的代码

  1. 在整个模块上运行 Black，在 CLI 上将其指定为 [SRC]...
  2. 使用 -c,--code TEXT 选项在 CLI 上将代码区域作为字符串传递。

以下实现显示了如何使用第二个选项执行此操作。原因是对整个模块应用黑色可能会改变行数，从而使通过选择开始和结束行号来选择代码区域的工作变得更加复杂。

可以实现第一个选项，但需要在 Black 格式化整个模块后将初始代码区域映射到最终代码区域。

让我们以以下代码为例，其中有许多明显的 PEP-8 违规（缺少空格和空行）：

"""
long multi-line
comment
"""
def foo(token:int=None)->None:
  a=token+1

class bar:
  foo:int=None
  
def the_simple_test():
    """the_simple_test"""
    pass

第 1 步。

使用黑色 as an external tool in the IDE 可以通过转到 File > Tools > External Tools 并单击 Add 或Edit 个图标。

感兴趣的是将正确的 Macros - (see point 3 "Parameter with macros") 从 PyCharm IDE 传递给调用 Black 并进行必要处理的自定义脚本。即你需要宏

  • FilePath - File Path
  • SelectionStartLine - Selected text start line number
  • SelectionEndLine - Select text end line number
  • PyInterpreterDirectory - The directory containing the Python interpreter selected for the project

但有时我想通过 PyCharm 在一个区域上执行 black -S。

您想作为参数传递的任何其他 Black CLI options 最好放在参数列表的末尾。

由于您可能在特定的 venv 上安装了 Black，因此该示例还使用了 PyInterpreterDirectory 宏。

截图说明了上述内容：

enter image description here

第 2 步。

您需要实现一个脚本来调用 Black 并与 IDE 交互。下面是一个工作示例。需要注意的是：

  1. 四行是特定于 OS/shell 的注释（根据您的环境调整它们应该是微不足道的）。
  2. 一些细节可以进一步调整，例如，实现做出了简单的选择。
import os
import pathlib
import tempfile
import subprocess
import sys

def region_to_str(file_path: pathlib.Path,start_line: int,end_line: int) -> str:

    file = open(file_path)
    str_build = list()

    for line_number,line in enumerate(file,start=1):
        if line_number > end_line:
            break
        elif line_number < start_line:
            continue
        else:
            str_build.append(line)

    return "".join(str_build)

def black_to_clipboard(py_interpeter,black_cli_options,code_region_str):

    py_interpreter_path = pathlib.Path(py_interpeter) / "python.exe"  # OS specific,.exe for Windows.

    proc = subprocess.Popen([py_interpreter_path,"-m","black",*black_cli_options,"-c",code_region_str],stdout=subprocess.PIPE)

    try:
        outs,errs = proc.communicate(timeout=15)
    except TimeoutExpired:
        proc.kill()
        outs,errs = proc.communicate()

    # By default Black outputs binary,decodes to default Python module utf-8 encoding.
    result = outs.decode('utf-8').replace('\r','')  # OS specific,remove \r from \n\r Windows new-line.

    tmp_dir_name = tempfile.gettempdir()
    tmp_file = tempfile.gettempdir() + "\\__run_black_tmp.txt"  # OS specific,escaped path separator.

    with open(tmp_file,mode='w+',encoding='utf-8',errors='strict') as out_file:
        out_file.write(result + '\n')

    command = 'clip < ' + str(tmp_file)  # OS specific,send result to clipboard for copy-paste.
    os.system(command)

def main(argv: list[str] = sys.argv[1:]) -> int:
    """External tool script to run black on a code region.

    Args:
        argv[0] (str): Path to module containing code region.
        argv[1] (str): Code region start line.
        argv[2] (str): Code region end line.
        argv[3] (str): Path to venv /Scripts directory.
        argv[4:] (str): Black CLI options.
    """
    # print(argv)
    lines_as_str = region_to_str(argv[0],int(argv[1]),int(argv[2]))
    black_to_clipboard(argv[3],argv[4:],lines_as_str)

if __name__ == "__main__":
    main(sys.argv[1:])

第 3 步。

困难的部分已经完成。让我们使用新功能。

通常在编辑器中选择您想要的行作为代码区域。必须强调这一点，因为前面的 SelectionStartLine 和 SelectionEndLine 宏需要选择才能工作。 （见下一个截图）。

第 4 步。

运行之前实现的外部工具。这可以通过在编辑器中右键单击并选择 External Tools > the_name_of_your_external_tool 来完成。

enter image description here

第 5 步。

简单粘贴（截图显示了运行外部工具并按Ctrl + v后的结果）。 第 2 步 中的实现将 Black 的输出复制到您操作系统的剪贴板，这似乎是更可取的解决方案，因为您可以通过这种方式更改编辑器内的文件，因此 Undo Ctrl + z 也可以工作。通过在编辑器外以编程方式覆盖文件来更改文件会不太流畅，并且可能需要在编辑器内刷新它。

enter image description here

第 6 步。

您可以通过 record a macro 前面的步骤和 associate it with a keyboard shortcut 在一次按键中获得上述功能（类似于复制粘贴 Ctrl + c + Ctrl + v).

enter image description here

结束注释。

  1. 如果您需要在步骤 2 中调试功能，还可以使用与外部工具配置相同的宏来配置 Run Configuration。

  2. 在使用剪贴板时要注意字符编码可以跨层更改，这一点很重要。我决定使用 clip 并直接从临时文件中读入它，这是为了避免在命令行上将代码字符串传递给 Black，因为 CMD Windows 编码默认不是 UTF-8。 （对于 Linux 用户，这应该更简单，但可能取决于您的系统设置。）

  3. 一个重要的注意事项是，您可以选择一个没有缩进级别的更广泛上下文的代码区域。这意味着，例如，如果您只在一个类中选择 2 个方法，它们将被传递给 Black 并使用模块级函数的缩进级别进行格式化。如果您小心地选择具有适当范围的代码区域，这应该不是问题。这也可以通过传递来自步骤 1 的附加宏 SelectionStartColumn - Select text start column number 并在步骤 2 脚本中的每一行前面添加该数量的空格来轻松解决。 （理想情况下，此类功能将由 Black 作为 CLI 选项实现。）无论如何，如果需要，使用 Tab 将区域置于适当的缩进级别非常容易。

  4. 问题的主要主题是如何将 Black 与 PyCharm IDE 集成到代码区域，因此演示第二个选项应该足以解决问题，因为第一个选项在大多数情况下仅添加实现特定的复杂性。 （答案已经足够长了。实现第一个选项的细节将为 Black 项目提供一个很好的功能/拉取请求。）

,

我对此进行了研究，因为它实际上看起来很有趣，我得出的结论是您可以使用：

black -S and_your_file_path

或：

black -c and_a_string

将传入的代码格式化为字符串。 我也会关注这个线程，因为它看起来很有趣。
我还将对此进行更多研究，如果我发现了什么，我会通知您。

macrosmacrospycharmpycharmpythonpython-black