zimports 0.6.1

zzzeek，你为什么写这样的程序，有十几个 pep8 导入修复器

我已经看过了很多。我需要一个能够

• 直接与 flake8-import-order 一起使用，这样我们就能保证导入匹配

• 具有 shell 能力，不仅仅是 vim 或 sublime text 的插件（Python Fix Imports，免费）

• 删除未使用的导入，而不仅仅是重新格式化（importanize）

• 重新格式化导入，而不仅仅是删除未使用的导入（autoflake）

• 不会遗漏删除未使用的导入，即使它位于多行导入中（autoflake）

• 将所有导入拆分为单独的行，而不仅仅是当行大于 80 个字符时（importanize）

• 仍然很简单（因为我们已经超越了最初的“极其简单”基线，因为所有问题最终都不是那么简单），因为（由于 pyflakes 和 flake8-import-order 已经做了大部分工作）这是一个极其简单的任务，这里（仍然）不需要一个庞大的应用程序。

使用方法

脚本可以在没有任何配置的情况下运行，选项如下

$ zimports --help
usage: zimports [-h] [-m APPLICATION_IMPORT_NAMES]
                [-p APPLICATION_PACKAGE_NAMES] [--style STYLE] [--multi-imports]
                [-k] [-kt] [--heuristic-unused HEURISTIC_UNUSED] [--statsonly]
                [-e] [--diff] [--stdout]
                filename [filename ...]

positional arguments:
  filename              Python filename(s) or directories

optional arguments:
  -h, --help            show this help message and exit
  -m APPLICATION_IMPORT_NAMES, --application-import-names APPLICATION_IMPORT_NAMES
                        comma separated list of names that should be
                        considered local to the application. reads from
                        [flake8] application-import-names by default.
  -p APPLICATION_PACKAGE_NAMES, --application-package-names APPLICATION_PACKAGE_NAMES
                        comma separated list of names that should be
                        considered local to the organization. reads from
                        [flake8] application-package-names by default.
  --style STYLE         import order styling, reads from [flake8] import-
                        order-style by default, or defaults to 'google'
  --multi-imports       If set, multiple imports can exist on one line
  -k, --keep-unused     keep unused imports even though detected as unused.
                        Implies keep-unused-type-checking
  -kt, --keep-unused-type-checking
                        keep unused imports even though detected as unused in
                        type checking blocks. zimports does not detect type usage
                        in comments or when used as string
  --heuristic-unused HEURISTIC_UNUSED
                        Remove unused imports only if number of imports is
                        less than <HEURISTIC_UNUSED> percent of the total
                        lines of code. Ignored in type checking blocks
  --statsonly           don't write or display anything except the file stats
  -e, --expand-stars    Expand star imports into the names in the actual
                        module, which can then have unused names removed.
                        Requires modules can be imported
  --diff                don't modify files, just dump out diffs
  --stdout              dump file output to stdout

目前，配置在中消费flake8参数，然后在中添加额外的zimports参数（自0.5.0版本起）——这两个文件的统一将在未来的版本中实现，可能是在flake8增加了toml支持时。

# setup.cfg

[flake8]
enable-extensions = G
ignore =
    A003,
    E203,E305,E711,E712,E721,E722,E741,
    F841,
    N801,N802,N806,
    W503,W504
import-order-style = google
application-import-names = sqlalchemy,test

# pyproject.toml, integrated with black

[tool.black]
line-length = 79
target-version = ['py37']


[tool.zimports]
black-line-length = 79
keep-unused-type-checking = true

# other options:
# multi-imports = true
# keep-unused = true

然后，在大多数干净的源树上的典型运行如下

$ zimports lib/
[Unchanged]     lib/sqlalchemy/inspection.py (in 0.0058 sec)
[Unchanged]     lib/sqlalchemy/log.py (in 0.0221 sec)

...

[Unchanged]     lib/sqlalchemy/orm/attributes.py (in 0.2152 sec)
[Unchanged]     lib/sqlalchemy/orm/base.py (in 0.0363 sec)
[Writing]       lib/sqlalchemy/orm/relationships.py ([2% of lines are imports] [source +0L/-2L] [3 imports removed in 0.3287 sec])
[Unchanged]     lib/sqlalchemy/orm/strategies.py (in 0.2237 sec)

程序有两种通用使用模式。一种是对已有整洁导入的应用程序的日常使用。在这样应用程序的源文件上运行zimports应该不会产生任何变化，除非是最近编辑过的源文件，可能需要对导入进行一些排序。这种使用模式类似于Black，你可以运行“zimports .”并找到需要调整的文件，而其他文件则保持不变。

另一种使用模式是对导入未组织的应用程序进行前端清理。在这种使用模式下，目标是使源文件被清理，以便可以直接运行zimports而无需对文件进行任何修改，包括所有必要的导入要么被本地使用，要么被标记为不删除。

在这个阶段可能会出现的问题包括，某些导入未使用且应该被删除，而其他看似未使用的导入实际上仍然被程序的另一部分使用。另一个问题是，在复杂情况下改变导入的顺序可能会因为创建无法解决的导入循环而使应用程序无法运行。最后，一些程序使用了import *，导入了一长串未知部分中的一些名称。提供了--keep-unused、--heuristic-unused和--expand-stars选项来帮助处理这些问题，直到代码可以完全重排，这样运行zimports就不再产生变化。

在某些应用程序中，可能存在明显未使用的导入，这些导入是从外部导入的，这个问题可能比较突出。为了允许那些在本地未使用的导入保留在源文件中，__all__ 部分的符号将不会被移除，同样，跟有 `` # noqa`` 注释的导入也不会被移除。这两种技术可以应用于那些在其他模块中使用但未在源文件中引用的导入。对于那些很少见的情况，即某些导入确实需要非常具体的导入顺序才能工作，这些导入可以跟一个 `` # noqa nosort`` 注释，这样这些行就会被添加到所有导入的末尾的特殊分组中，在那里它们不会被移除，并且它们之间的顺序将会被保留。

当前程序要求您至少传递一个文件名或目录名作为参数。它也没有 Black 具有的文件缓存功能，这允许它只查看自上次运行以来已更改的文件。计划是检查它是否在一个 git 仓库中，如果没有给出文件名，它将运行要提交的文件。

作为 git 钩子使用

zimports 可以与 pre-commit git 钩子框架一起使用。要添加插件，将以下内容添加到您的 .pre-commit-config.yaml 文件中。注意，rev: 属性指的是要使用的 zimports 的 git 标签或修订号，例如 "master" 或 "0.1.3"

repos:
-   repo: https://github.com/sqlalchemyorg/zimports/
    rev: v0.4.5
    hooks:
    -   id: zimports