"glob" --- Unix style pathname pattern expansion
************************************************

**源代码:** Lib/glob.py

======================================================================

"glob" 模块会按照 Unix shell 所使用的规则找出所有匹配特定模式的路径名
称，但返回结果的顺序是不确定的。 波浪号扩展不会生效，但 "*", "?" 以及
用 "[]" 表示的字符范围将被正确地匹配。 这是通过配合使用 "os.scandir()"
和 "fnmatch.fnmatch()" 函数来实现的，而不是通过实际发起调用子 shell。

请注意以点号 (".") 打头的文件只能用同样以点号打头的模式来匹配，这不同
于 "fnmatch.fnmatch()" 或 "pathlib.Path.glob()"。 （对于波浪号和 shell
变量扩展，请使用 "os.path.expanduser()" 和 "os.path.expandvars()"。）

对于字面值匹配，请将原字符用方括号括起来。 例如，"'[?]'" 将匹配字符
"'?'"。

参见: "pathlib" 模块提供高级路径对象。

glob.glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

   返回一个匹配 *pathname* 的可能为空的路径名列表，其中的元素必须为包
   含路径信息的字符串。 *pathname* 可以是绝对路径 (如
   "/usr/src/Python-1.5/Makefile") 或相对路径 (如
   "../../Tools/*/*.gif")，并可包含 shell 风格的通配符。 无效的符号链
   接也将包括在结果中 (如像在 shell 中一样)。 结果是否排序取决于具体文
   件系统。 如果某个符合条件的文件在调用此函数期间被移除或添加，是否包
   括该文件的路径是没有规定的。

   如果 *root_dir* 不为 "None"，则它应当是指明要搜索的根目录的 *path-
   like object*。 它用在 "glob()" 上与在调用它之前改变当前目录有相同的
   效果。 如果 *pathname* 为相对路径，结果将包含相对于 *root_dir* 的路
   径。

   本函数带有 *dir_fd* 参数，支持 基于目录描述符的相对路径。

   如果 *recursive* 为真值，则模式 ""**"" 将匹配目录中的任何文件以及零
   个或多个目录、子目录和符号链接。 如果模式加了一个 "os.sep" 或
   "os.altsep" 则将不匹配文件。

   如果 *include_hidden* 为真值，""**"" 模式将匹配隐藏目录。

   引发一个 审计事件 "glob.glob" 附带参数 "pathname", "recursive"。

   引发一个 审计事件 "glob.glob/2"，附带参数 "pathname", "recursive",
   "root_dir", "dir_fd"。

   备注:

     在一个较大的目录树中使用 ""**"" 模式可能会消耗非常多的时间。

   备注:

     如果 *pathname* 包含多个 ""**"" 模式并且 *recursive* 为真值则此函
     数可能返回重复的路径名。

   在 3.5 版本发生变更: 支持使用 ""**"" 的递归 glob。

   在 3.10 版本发生变更: 添加了 *root_dir* 和 *dir_fd* 形参。

   在 3.11 版本发生变更: 增加了 *include_hidden* 形参。

glob.iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

   返回一个 *iterator*，它会产生与 "glob()" 相同的结果，但不会实际地同
   时保存它们。

   引发一个 审计事件 "glob.glob" 附带参数 "pathname", "recursive"。

   引发一个 审计事件 "glob.glob/2"，附带参数 "pathname", "recursive",
   "root_dir", "dir_fd"。

   备注:

     如果 *pathname* 包含多个 ""**"" 模式并且 *recursive* 为真值则此函
     数可能返回重复的路径名。

   在 3.5 版本发生变更: 支持使用 ""**"" 的递归 glob。

   在 3.10 版本发生变更: 添加了 *root_dir* 和 *dir_fd* 形参。

   在 3.11 版本发生变更: 增加了 *include_hidden* 形参。

glob.escape(pathname)

   转义所有特殊字符 ("'?'", "'*'" 和 "'['")。 这适用于当你想要匹配可能
   带有特殊字符的任意字符串字面值的情况。 在 drive/UNC 共享点中的特殊
   字符不会被转义，例如在 Windows 上 "escape('//?/c:/Quo vadis?.txt')"
   将返回 "'//?/c:/Quo vadis[?].txt'"。

   Added in version 3.4.

例如，考虑一个包含以下内容的目录：文件 "1.gif", "2.txt", "card.gif" 以
及一个子目录 "sub" 其中只包含一个文件 "3.txt".  "glob()" 将产生如下结
果。 请注意路径的任何开头部分都将被保留。:

   >>> import glob
   >>> glob.glob('./[0-9].*')
   ['./1.gif', './2.txt']
   >>> glob.glob('*.gif')
   ['1.gif', 'card.gif']
   >>> glob.glob('?.gif')
   ['1.gif']
   >>> glob.glob('**/*.txt', recursive=True)
   ['2.txt', 'sub/3.txt']
   >>> glob.glob('./**/', recursive=True)
   ['./', './sub/']

如果目录包含以 "." 打头的文件，它们默认将不会被匹配。 例如，考虑一个包
含 "card.gif" 和 ".card.gif" 的目录:

   >>> import glob
   >>> glob.glob('*.gif')
   ['card.gif']
   >>> glob.glob('.c*')
   ['.card.gif']

参见:

  模块 "fnmatch"
     Shell 风格文件名（而非路径）扩展
