Python-glob2 项目技术文档

1. 安装指南

Python-glob2 是 Python 标准库中内置 glob 模块的扩展版本，它增加了一些新特性。要安装 Python-glob2，请按照以下步骤进行：

• 确保您的系统已安装 Python 2 或 Python 3（已测试 3.3 版本）。
• 打开命令行工具。
• 输入以下命令安装 Python-glob2：

pip install glob2

确保您的 pip 版本是最新的，如果不是，请先升级 pip：

pip install --upgrade pip

2. 项目使用说明

Python-glob2 提供了以下功能：

• 支持捕获与 glob 模式匹配的文本，并返回这些匹配项以及文件名。
• 支持递归的 '**' globbing 语法，类似于 bash shell 的 globstar 选项。
• 允许替换文件系统函数，以便在虚拟文件系统上进行 glob 操作。

以下是使用 Python-glob2 的一些示例：

匹配返回

import glob2

for filename, (version,) in glob2.iglob('./binaries/project-*.zip', with_matches=True):
    print(version)

递归 glob

import glob2

all_header_files = glob2.glob('src/**/*.h')
# 输出类似于 ['src/fs.h', 'src/media/mp3.h', 'src/media/mp3/frame.h', ...]

注意，** 必须单独出现在目录元素中才具有特殊含义。**h 将不会得到期望的效果。

** 将匹配当前目录下的点（"."），如果这不是您想要的，可以使用 */**/*.py。

自定义 Globber

from glob2 import Globber

class VirtualStorageGlobber(Globber):
    def __init__(self, storage):
        self.storage = storage
    
    def listdir(self, path):
        # 如果路径不是目录，则必须引发 os.error
        return self.storage.listdir(path)
    
    def exists(self, path):
        return self.storage.exists(path)
    
    def isdir(self, path):
        # 仅用于以斜杠结尾的语法（如：`foo/`）。
        return self.storage.isdir(path)
    
    def islink(self, path):
        # 仅用于递归 glob（如：`**`）。
        return self.storage.islink(path)

globber = VirtualStorageGlobber(sftp_storage)
globber.glob('/var/www/**/*.js')

如果无法为存储实现 isdir 和/或 islink 方法，可以将它们设置为返回一个固定值，这将导致以下后果：

• 如果 isdir 返回 True，则目录结尾的 glob 表达式将返回所有项目（包括非目录），如果返回 False，则同样表达式将不返回任何内容。

• 如果 islink 返回 True，递归 globbing 语法 ** 将跟随所有链接。如果返回 False，它将完全不起作用。

3. 项目 API 使用文档

Python-glob2 的 API 包括以下方法和功能：

• iglob(pattern, recursive=False, with_matches=False)：返回一个生成器，生成所有与模式匹配的路径名。如果 recursive 为 True，将使用递归搜索。with_matches 为 True 时，将返回匹配的文本。

• glob(pattern, recursive=False, with_matches=False)：与 iglob 类似，但返回一个列表而不是生成器。

• Globber 类：允许自定义文件系统函数，用于在虚拟文件系统上进行 glob 操作。

4. 项目安装方式

请参考本文档的“安装指南”部分，安装方式是通过 pip 包管理工具进行安装。