"glob" --- Unix 风格的路径名模式扩展
************************************

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

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

"glob" 模块会使用与 Unix shell 类似的模式匹配规则来查找路径名称。波浪
号扩展不会生效，但 "*", "?" 以及用 "[]" 表示的字符范围将被正确地匹配。
这是通过配合使用 "os.scandir()" 和 "fnmatch.fnmatch()" 函数完成的，而
不是通过实际唤起子 shell。

备注:

  路径名称不会以特定的顺序返回。如果你需要特定的顺序，请对结果进行排序
  。

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

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

"glob" 模块定义了下列函数：

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* 参数，支持 基于目录描述符的相对路径。

   If *recursive* is true, the pattern ""**"" will match any files and
   zero or more directories, subdirectories and symbolic links to
   directories. If the pattern is followed by an "os.sep" or
   "os.altsep" then files will not match.

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

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

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

   备注:

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

   备注:

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

   备注:

     任何因扫描文件系统而引发的 "OSError" 异常都会被抑制。 这包括访问
     没有读取权限的目录时的 "PermissionError"。

   在 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* 为真值则此函
     数可能返回重复的路径名。

   备注:

     任何因扫描文件系统而引发的 "OSError" 异常都会被抑制。 这包括访问
     没有读取权限的目录时的 "PermissionError"。

   在 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.

glob.translate(pathname, *, recursive=False, include_hidden=False, seps=None)

   Convert the given path specification to a regular expression for
   use with "re.prefixmatch()". The path specification can contain
   shell-style wildcards.

   例如：

   >>> import glob, re
   >>>
   >>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True)
   >>> regex
   '(?s:(?:.+/)?[^/]*\\.txt)\\z'
   >>> reobj = re.compile(regex)
   >>> reobj.prefixmatch('foo/bar/baz.txt')
   <re.Match object; span=(0, 15), match='foo/bar/baz.txt'>

   路径分隔符与部件对该函数是有意义的，这与 "fnmatch.translate()" 不同
   。在默认情况下通配符不会匹配路径分隔符，而 "*" 模式部件将精确匹配一
   个路径部件。

   如果 *recursive* 为真值，则模式部件 ""**"" 将匹配任意数量的路径部件
   。

   如果 *include_hidden* 为真值，则通配符可以匹配以点号 (".") 打头的路
   径部件。

   可以向 *seps* 参数提供一个由路径分隔符组成的序列。如果未给出，则将
   使用 "os.sep" 和 "altsep" (如果可用)。

   参见:

     "pathlib.PurePath.full_match()" 和 "pathlib.Path.glob()" 方法，它
     们将调用此函数来实现模式匹配和 glob 操作。

   Added in version 3.13.


例子
====

考虑一个包含以下文件的目录："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 风格的文件名（而非路径）扩展。

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