Globality black

免责声明

技术讨论

black的包装器，增加了预处理和后处理功能，以更好地与Globality约定保持一致。

globality-black执行以下步骤

• 预处理：以防止black操作
• black
• 后处理：以撤销/纠正black操作

注意：如果您不熟悉black（或需要刷新），请阅读我们的Black刷新。

目录

• Globality black
• 目录
• 安装
• 用法
  • CLI
  • Pycharm
  • JupyterLab
  • VScode
    • 与远程协作
    • 快捷键
    • 与笔记本协作
• 功能
  • 空行
  • 点链
  • 长度为1的元组
  • 列表推导式
    • 在globality-black之前
    • 在globality-black之后
  • 部分禁用globality-black
• 待办/未来工作
• Black刷新
  • 魔法逗号
• 常见问题解答
• 测试
• 贡献
  • 提交和问题
  • 提交拉取请求
  • 行为准则

安装

pip install globality-black

用法

使用globality-black有两种方式，通过CLI或导入库中的助手。接下来，我们将展示一些典型用例。

CLI

请参阅运行globality-black --help的命令行参数。

Pycharm

要在PyCharm中使用globality-black，请转到PyCharm -> 首选项... -> 工具 -> 外部工具 -> 点击+符号添加新外部工具。

建议配置以格式化当前文件

• 程序：指向globality-black的路径，例如：/Users/marty-mcfly/miniconda3/envs/gb/bin/globality-black
• 参数：$FilePath$
• 工作目录：$ProjectFileDir$

推荐配置以检查整个仓库（但不进行格式化）

• 程序：指向globality-black的路径，例如：/Users/marty-mcfly/miniconda3/envs/gb/bin/globality-black
• 参数：. --check
• 工作目录：$ProjectFileDir$

接下来，配置一个快捷键，如这里。

JupyterLab

我们可以利用这个扩展，使用自定义格式化器。以下是如何获取以下选项的说明

有两种方式应用globality-black，见左侧，或者点击“代码”旁边的按钮。我们将配置扩展，使其在点击此按钮时应用isort + globality-black管道。

为此，安装扩展，生成jupyter lab的配置文件并编辑它

pip install jupyterlab_code_formatter
jupyter lab --generate-config
vim ~/.jupyter/jupyter_lab_config.py

你可能已经在jupyter_lab_config中设置了某些配置。如果是这样，你可能想省略上面的第二个命令，并使用vim进行编辑。

无论如何，我们将添加以下代码

from jupyterlab_code_formatter.formatters import SERVER_FORMATTERS
from globality_black.jupyter_formatter import GlobalityBlackFormatter
SERVER_FORMATTERS['globality-black'] = GlobalityBlackFormatter(line_length=100)

然后，转到扩展首选项，并添加

{
    "preferences": {
        "default_formatter": {
            "python": [
                "isort",
                "globality-black",
            ],
        }
    },
    "isort": {
           "combine_as_imports": true,
           "force_grid_wrap": 4,
           "force_to_top": "true",
           "include_trailing_comma": true,
           "known_third_party": ["wandb", "tqdm"],
           "line_length": 100,
           "lines_after_imports": 2,
           "multi_line_output": 3,
    }
}

注意

• 上述最后一步将转换为保存在~/.jupyter/lab/user-settings/@ryantam626/中的用户设置。
• 该扩展应用于笔记本中的所有单元格。如果感兴趣，可以配置它仅应用于当前单元格。
• 该扩展独立应用于每个单元格。因此，如果不同单元格中出现了多个导入，它们不会在笔记本顶部合并。

VScode

要在VScode中使用globality-black，请安装扩展External formatters。

然后，转到首选项：设置（JSON）。将打开一个settings.json文件。将以下内容添加到文件中

"[python]": {
        "editor.codeActionsOnSave": {
            "source.organizeImports": true
        },
        "editor.defaultFormatter": "SteefH.external-formatters",
    },
    "isort.args":["--profile", "black"],

这将配置isort在保存时运行，并将glo-black作为默认格式化器。另外，添加以下内容

[
    "externalFormatters.languages": {
        "python": {
            "command": "$PATH_TO_ENV/bin/globality-black",
            "arguments": [
                "-",
            ]
        }
    },
    "isort.interpreter": [
        "$PATH_TO_ENV/bin/python"
    ],
]

设置或将$PATH_TO_ENV替换为你需要访问globality-black Python环境的任何内容。

与远程协作

重要：这两个路径必须是绝对路径，并且需要在VScode的任何地方都相同。这意味着如果你在远程使用VScode（例如EC2实例），则需要存在相同的路径。显然，这是不可能的，因为例如在EC2中你将会有/home/ubuntu/...，而在你的机器上将是/Users/john/...。一个解决方案是在你的实例中创建一个符号链接，例如

sudo ln -s /home/ubuntu /Users/john

快捷键

要配置快捷键，请从调色板（command+shift+p）转到首选项：键盘快捷键（JSON）。将打开keybindings.json文件。将以下内容添加到该文件中

[
    {
        "key": "cmd+shift+j",
        "command": "editor.action.formatDocument",
        "when": "editorHasDocumentFormattingProvider && editorTextFocus && !editorReadonly && !inCompositeEditor"
    }
]

这将允许您在当前打开的文件上运行globality-black，通过stdin传递文件的内容。

与笔记本协作

要格式化笔记本，有一个快捷键

{
    "key": "shift+alt+f",
    "command": "notebook.formatCell",
    "when": "editorHasDocumentFormattingProvider && editorTextFocus && inCompositeEditor && notebookEditable && !editorReadonly && activeEditor == 'workbench.editor.notebook'",
}

您可以修改它，如果您不喜欢这个组合。这将使用默认格式化器格式化当前单元格。我没有找到运行isort的方法。有一个“在保存笔记本时格式化”选项，但这并不完全是我们为Python文件配置的。那将运行isort + glo-black。

功能

空行

Black将删除下面wandb和scikit-learn之后的空行

graph.use(
    "wandb",

    "scikit-learn",

    # we love pandas
    "pandas",
)

globality-black保护那些假设开发者添加它们是为了可读性。

点链

类似于“空白行”功能，“点链”功能允许保持块相同

return (
    df_field[COLUMNS_PER_FIELD[name]]
    .dropna(subset=["column"])
    .reset_index(drop=True)
    .assign(mapped_type=MAP_DICT[name])
)

LABELS = set(
    df[df.labels.apply(len) > 0]
    .flag.apply(curate)
    .apply(normalize)
    .unique()
)

在此功能中，我们不会“爆炸”任何东西，而是保护假设它是为了可读性而故意编写的代码。

长度为1的元组

这是一个非常简单且特定的功能。Black（至少到21.9b0）有一个错误，使得只有一个元素的元组被压缩成这样

x = (
    3,
)

变成了

x = (3,)

请参阅https://github.com/psf/black/issues/1139#issuecomment-951014094。使用globality-black将保护这些。

列表推导式

分解列表推导式

• 所有字典推导式
• 任何带有if的推导式
• 任何带有多个for循环的推导式（以下有示例）
• 列表/集合推导式，其中元素
  • 包含三元运算符（见以下示例）
  • 包含另一个推导式

对于其他所有内容，我们依赖于 black。示例

在globality-black之前

[3 for _ in range(10)]

[3 for i in range(10) if i < 4]

{"a": 3 for _ in range(4)}

{"a": 3 for _ in range(4) if i < 4}

["odd" if i %% 2 == 0 else "even" for _ in range(10)]

double_comp1 = [3*i*j for i in range(10) for j in range(4)]

double_comp2 = [[i for i in range(7) if i < 5] for j in range(10)]

double_comp3 = {i: [i for i in range(7) if i < 5] for j in range(10) if i < 2}

在globality-black之后

[3 for _ in range(10)]

[
    3
    for i in range(10)
    if i < 4
]

{
    "a": 3
    for _ in range(4)
}

{
    "a": 3
    for _ in range(4)
    if i < 4
}

[
    "odd" if i %% 2 == 0 else "even"
    for _ in range(10)
]

double_comp1 = [
    3 * i * j
    for i in range(10)
    for j in range(4)
]

double_comp2 = [
    [i for i in range(7) if i < 5]
    for j in range(10)
]

double_comp3 = {
    i: [i for i in range(7) if i < 5]
    for j in range(10)
    if i < 2
}

注意，在最后两个推导式中，即使有if语句，嵌套推导式也不会展开。这是globality-black的一个限制，但我们在日常案例中认为这并不常见。如果您真的想展开这些并使globality-black尊重它，请使用下一部分解释的功能。

部分禁用globality-black

如果您看到某个不想应用globality-black的块，请用# fmt.off和# fmt:on包裹它，它将被忽略。请注意，这与black的语法相同。例如，为了可读性，您可能想这样做

# fmt: off
files_to_read = [
    (f"{key1}_{key2}", key1, key2, key1 + key2)
    for key1 in range(10)
]
# fmt: on

请注意，默认情况下（与black相同），globality-black会将上面的表达式写成一行的代码。

待办/未来工作

• 根据某些标准展开三元运算符
• 嵌套推导式
• 由于这个，我们有一个用于单元素子脚本的魔法逗号

如果您发现任何问题，请给我们反馈，并检查known_failed

Black刷新

black是一个有偏见的Python格式化程序，它试图尽可能多地节省垂直空间。在这方面，它会将行压缩到配置的最大字符长度。默认情况下，black是88个字符，而在globality-black中，我们使用一个默认的100个字符，这是为全球性的仓库所同意的。如果您想自定义最大字符长度，请将一个pyproject.toml文件添加到您的仓库根目录。这与black的工作方式相同，globality-black将从这个配置中获取您的配置。

查看他们的README中black是如何工作的。这部分特别有用，特别是这一节，其中解释了重要的新功能。

魔法逗号

black在2020年底增加了一个功能，我们称之为“魔法逗号”。这是第一个例子，其中black在除了fmt:off和fmt:on忽略black之外的方式上给予开发者一定的自由（如何最终看起来像代码）。更多信息请参阅这里。

常见问题解答

以下是我们列出的一些在向其他团队展示此项目时提出的问题和解决方案

我喜欢这个项目，但这会毁掉我们所有的git历史和git指责

我们的建议是

1. 为您的所有仓库创建一个大的PR，并一次性审查这些更改。
2. 在您的仓库中添加一个.git-blame-ignore-revs文件，忽略应用globality-black的大批量提交。有关更多详细信息，请参阅这里。

我大多数更改都喜欢，但在一些地方我真的很喜欢我的代码风格

没问题，对于那些您更喜欢自己风格的特定情况，只需用fmt:off和fmt:on包裹该块，请参阅部分禁用Globality Black部分。

每行100个字符对我来说太短/太长了

只需将一个pyproject.toml添加到您的仓库根目录（就像这个项目中的那样）并指定您首选的长度，请参阅Black刷新部分。

在应用更改之前我想知道会发生什么变化

请使用CLI中的--diff选项，请参阅CLI部分。

我想展开参数列表，但globality-black将其压缩到一行

请使用神奇逗号功能，见神奇逗号。

测试

按照以下方式运行测试

bash entrypoint.sh test

或者简单地说

pytest .

一些选项

• -s显示打印信息，以便调试
• --pdb在发生异常时触发调试器
• pytest route_to_test测试特定的测试文件
• pytest route_to_test::test_function测试特定的测试函数
• pytest route_to_test::test_function[test_case]
• --cov-report term显示覆盖率

您可能可以在entrypoint.sh中找到其他代码检查器。注意，如果您打开一个拉取请求，这些将针对您的代码运行。

贡献

欢迎所有贡献、错误报告、安全问题、错误修复、文档改进、增强和想法。本部分是根据pandas 贡献指南改编和简化的。

提交和问题

错误报告、安全问题以及增强请求是使开源软件更稳定的重要部分，并通过 Github 的问题进行整理。在报告问题或请求时，请填写完整的表格，以确保其他人以及核心开发团队能够完全了解问题的范围。

问题将显示给社区，并开放给其他人的评论/想法。

提交拉取请求

deboiler托管在GitHub上，要做出贡献，您需要注册一个免费的GitHub帐户。我们使用Git进行版本控制，以允许许多人共同参与项目。如果您是Git新手，可以参考上面引用的pandas贡献指南中的资源。

此外，该项目遵循标准的分支工作流程，即贡献者将仓库分支，进行更改，创建功能分支，推送更改，然后创建拉取请求。为了避免重复，请遵循上面引用的pandas贡献指南中的所有说明。

行为准则

作为本项目的贡献者和维护者，您应遵守行为准则。更多信息可以在贡献者行为准则中找到。

=============== Globality black

v0.1.0

• 待办事项