cpburnz/python-pathspec
GitHub: cpburnz/python-pathspec
这是一个用于实现 gitignore 风格文件路径模式匹配的 Python 实用库。
Stars: 227 | Forks: 52
# PathSpec
*pathspec* 是一个用于文件路径模式匹配的实用库。目前这
只包括 Git 的 `gitignore`_ 模式匹配。
.. _`gitignore`: http://git-scm.com/docs/gitignore
## 教程
假设你有一个 "Projects" 目录并且想要备份它，但只
包含特定文件，并根据特定条件忽略其他文件::
```
>>> from pathspec import PathSpec
>>> # The gitignore-style patterns for files to select, but we're including
>>> # instead of ignoring.
>>> spec_text = """
...
... # This is a comment because the line begins with a hash: "#"
...
... # Include several project directories (and all descendants) relative to
... # the current directory. To reference only a directory you must end with a
... # slash: "/"
... /project-a/
... /project-b/
... /project-c/
...
... # Patterns can be negated by prefixing with exclamation mark: "!"
...
... # Ignore temporary files beginning or ending with "~" and ending with
... # ".swp".
... !~*
... !*~
... !*.swp
...
... # These are python projects so ignore compiled python files from
... # testing.
... !*.pyc
...
... # Ignore the build directories but only directly under the project
... # directories.
... !/*/build/
...
... """
```
``PathSpec`` 类提供了围绕模式实现的抽象，
我们希望将我们的模式编译为 "gitignore" 模式。你可以将其称为
已编译模式列表的包装器::
```
>>> spec = PathSpec.from_lines('gitignore', spec_text.splitlines())
```
如果我们想手动编译模式，我们可以直接使用 ``GitIgnoreBasicPattern``
类。它在 "gitignore" 的后台使用，内部将
模式转换为正则表达式::
```
>>> from pathspec.patterns.gitignore.basic import GitIgnoreBasicPattern
>>> patterns = map(GitIgnoreBasicPattern, spec_text.splitlines())
>>> spec = PathSpec(patterns)
```
``PathSpec.from_lines()`` 是一个简化此操作的类方法。
如果你想在文件中加载模式，你也可以直接
传递文件对象::
```
>>> with open('patterns.list', 'r') as fh:
>>> spec = PathSpec.from_lines('gitignore', fh)
```
你可以对整个目录树执行匹配::
```
>>> matches = set(spec.match_tree_files('path/to/directory'))
```
或者你可以对一组特定的文件路径执行匹配::
```
>>> matches = set(spec.match_files(file_paths))
```
或者检查单个文件是否匹配::
```
>>> is_matched = spec.match_file(file_path)
```
实际上 "gitignore" 有两种实现。基本实现被
``PathSpec`` 使用，并遵循 `gitignore`_ 所记录的模式。
然而，Git 的行为与记录的模式不同。有一些
边缘情况，特别是 Git 允许包含来自被排除
目录中的文件，这似乎与文档相矛盾。``GitIgnoreSpec``
处理了这些情况，以更接近地复现 Git 的行为::
```
>>> from pathspec import GitIgnoreSpec
>>> spec = GitIgnoreSpec.from_lines(spec_text.splitlines())
```
你无需为 ``GitIgnoreSpec`` 指定模式风格，因为它在内部
应始终使用 ``GitIgnoreSpecPattern``。
## 性能
在 Python 中对数千个文件运行大量正则表达式匹配
很慢。可以使用替代的正则表达式后端来
提高性能。``PathSpec`` 和 ``GitIgnoreSpec`` 都接受一个 ``backend``
参数来控制后端。默认值为 "best"，可自动
选择最佳可用后端。目前有 3 个后端。
"simple" 后端是默认的，它简单地使用通常创建的 Python ``re.Pattern``
对象。当只有 1 或 2 个模式时，这可能是最快的。
"hyperscan" 后端使用 `hyperscan`_ 库。Hyperscan 往往
比 "simple" 快至少 2 倍，但通常比 "re2" 慢。在模式
数量为 1-25 的适当条件下，这可能比 "re2" 更快。
"re2" 后端使用 `google-re2`_ 库（不要与
PyPI 上的 *re2* 库混淆，该库是无关的且已被废弃）。Google 的 re2 往往
明显快于 "simple"，且在高模式数量下比 "hyperscan" 快 3 倍。
有关原生 Python 正则表达式和可选后端之间的比较，请参见 `benchmarks_backends.md`_。
.. _`benchmarks_backends.md`: https://github.com/cpburnz/python-pathspec/blob/master/benchmarks_backends.md
.. _`google-re2`: https://pypi.org/project/google-re2/
.. _`hyperscan`: https://pypi.org/project/hyperscan/
## 常见问题解答
## 1. 我该如何忽略像 *.gitignore* 这样的文件？
``GitIgnoreSpec``（以及 ``PathSpec``）默认正向匹配文件。要查找
需保留的文件，并排除像 *.gitignore* 这样的文件，你需要
设置 ``negate=True`` 来反转结果::
```
>>> from pathspec import GitIgnoreSpec
>>> spec = GitIgnoreSpec.from_lines([...])
>>> keep_files = set(spec.match_tree_files('path/to/directory', negate=True))
>>> ignore_files = set(spec.match_tree_files('path/to/directory'))
```
## 许可证
*pathspec* 在 `Mozilla Public License Version 2.0`_ 下授权。有关
更多信息，请参见 `LICENSE`_ 或 `FAQ`_。
简而言之，你可以将 *pathspec* 用于任何闭源或开源项目，
而不会影响更大作品的许可，只要你：
- 给予应有的署名，
- 并发布对 *pathspec* 所做的任何自定义更改。
.. _`Mozilla Public License Version 2.0`: http://www.mozilla.org/MPL/2.0
.. _`LICENSE`: LICENSE
.. _`FAQ`: http://www.mozilla.org/MPL/2.0/FAQ.html
## 源码
*pathspec* 的源码可从 GitHub 仓库
`cpburnz/python-pathspec`_ 获取。
.. _`cpburnz/python-pathspec`: https://github.com/cpburnz/python-pathspec
## 安装
*pathspec* 可通过 `PyPI`_ 进行安装::
```
pip install pathspec
```
*pathspec* 也可以从源码构建。以下软件包将
是必需的：
- `build`_ (>=0.6.0)
然后可以通过以下命令构建和安装 *pathspec*::
```
python -m build
pip install dist/pathspec-*-py3-none-any.whl
```
可以安装以下可选依赖项：
- `google-re2`_: 启用可选的 "re2" 后端。
- `hyperscan`_: 启用可选的 "hyperscan" 后端。
- `typing-extensions`_: 改进部分类型提示。
.. _`PyPI`: http://pypi.python.org/pypi/pathspec
.. _`build`: https://pypi.org/project/build/
.. _`typing-extensions`: https://pypi.org/project/typing-extensions/
## 文档
*pathspec* 的文档可在 `Read the Docs`_ 上找到。
完整的变更历史可在 `CHANGES.rst`_ 和 `Change History`_ 中找到。
升级指南可在 `UPGRADING.rst`_ 和 `Upgrade Guide`_ 中找到。
.. _`CHANGES.rst`: https://github.com/cpburnz/python-pathspec/blob/master/CHANGES.rst
.. _`Change History`: https://python-path-specification.readthedocs.io/en/stable/changes.html
.. _`Read the Docs`: https://python-path-specification.readthedocs.io
.. _`UPGRADING.rst`: https://github.com/cpburnz/python-pathspec/blob/master/UPGRADING.rst
.. _`Upgrade Guide`: https://python-path-specification.readthedocs.io/en/stable/upgrading.html
## 其他语言
相关项目 `pathspec-ruby`_（由 *highb* 提供）提供了一个类似的库作为
一个 `Ruby gem`_。
.. _`pathspec-ruby`: https://github.com/highb/pathspec-ruby
.. _`Ruby gem`: https://rubygems.org/gems/pathspec
标签：Git, gitignore, SOC Prime, 代码实用工具, 工具库, 开发工具, 文件备份, 文件路径处理, 文件过滤, 模式匹配, 自动化资产收集, 路径匹配, 逆向工具, 通配符