"glob" --- Unix 風格的路徑名稱模式擴展
**************************************

**原始碼：**Lib/glob.py

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

"glob" 模組根據 Unix shell 使用的規則查找與指定模式匹配的所有路徑名稱
，結果以任意順序回傳。沒有波浪號 (tilde) 擴展，但是 "*"、"?" 和用 "[]"
表示的字元範圍將被正確匹配。這是透過同時使用 "os.scandir()" 和
"fnmatch.fnmatch()" 函式來完成的，而沒有實際調用 subshell。

請注意，以點 (".") 開頭的檔案只能與同樣以點開頭的模式匹配，這與
"fnmatch.fnmatch()" 或 "pathlib.Path.glob()" 不同。（對於波浪號和
shell 變數擴展，請使用 "os.path.expanduser()" 和
"os.path.expandvars()"。）

對於文本 (literal) 匹配，將元字元 (meta-character) 括在方括號中。例如
，"'[?]'" 會匹配 "'?'" 字元。

The "glob" module defines the following functions:

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

   回傳與 *pathname* 匹配、可能為空的路徑名稱 list，它必須是包含路徑規
   範的字串。 *pathname* 可以是絕對的（如
   "/usr/src/Python-1.5/Makefile"）或相對的（如 "../../Tools/*/*.gif"
   ），並且可以包含 shell 樣式的通用字元 (wildcard)。已損壞的符號連接
   也會（如同在 shell）被包含在結果中。結果是否排序取決於檔案系統
   (file system)。如果在呼叫此函式期間刪除或新增滿足條件的檔案，則結果
   不一定會包含該檔案的路徑名稱。

   如果 *root_dir* 不是 "None"，它應該是一個指定搜索根目錄的 *path-
   like object*。它在呼叫它之前更改當前目錄的影響與 "glob()" 相同。如
   果 *pathname* 是相對的，結果將包含相對於 *root_dir* 的路徑。

   此函式可以支援以 *dir_fd* 參數使用相對目錄描述器的路徑。

   如果 *recursive* 為真，模式 ""**"" 將匹配任何檔案、零個或多個目錄、
   子目錄和目錄的符號連結。如果模式後面有 "os.sep" 或 "os.altsep" 那麼
   檔案將不會被匹配。

   如果 *include_hidden* 為真，""**"" 模式將匹配被隱藏的目錄。

   引發一個附帶引數 "pathname"、"recursive" 的稽核事件 "glob.glob"。

   引發一個附帶引數 "pathname"、"recursive"、"root_dir"、"dir_fd" 的稽
   核事件 "glob.glob/2"。

   備註:

     在大型目錄樹中使用 ""**"" 模式可能會消耗過多的時間。

   備註:

     This function may return duplicate path names if *pathname*
     contains multiple ""**"" patterns and *recursive* is true.

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

   回傳一個會產生與 "glob()" 相同的值的 *iterator* ，而不是同時存儲全
   部的值。

   引發一個附帶引數 "pathname"、"recursive" 的稽核事件 "glob.glob"。

   引發一個附帶引數 "pathname"、"recursive"、"root_dir"、"dir_fd" 的稽
   核事件 "glob.glob/2"。

   備註:

     This function may return duplicate path names if *pathname*
     contains multiple ""**"" patterns and *recursive* is true.

   在 3.5 版的變更: 支援以 ""**"" 使用遞迴 glob。

   在 3.10 版的變更: 新增 *root_dir* 與 *dir_fd* 參數。

   在 3.11 版的變更: 新增 *include_hidden* 參數。

glob.escape(pathname)

   跳脫 (escape) 所有特殊字元（"'?'"、"'*'" 和 "'['"）。如果你想匹配其
   中可能包含特殊字元的任意文本字串，這將會很有用。驅動器 (drive)/UNC
   共享點 (sharepoints) 中的特殊字元不會被跳脫，例如在 Windows 上，
   "escape('//?/c:/Quo vadis?.txt')" 會回傳 "'//?/c:/Quo
   vadis[?].txt'"。

   在 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.match()". The path specification can contain shell-
   style wildcards.

   For example:

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

   Path separators and segments are meaningful to this function,
   unlike "fnmatch.translate()". By default wildcards do not match
   path separators, and "*" pattern segments match precisely one path
   segment.

   If *recursive* is true, the pattern segment ""**"" will match any
   number of path segments.

   If *include_hidden* is true, wildcards can match path segments that
   start with a dot (".").

   A sequence of path separators may be supplied to the *seps*
   argument. If not given, "os.sep" and "altsep" (if available) are
   used.

   也參考:

     "pathlib.PurePath.full_match()" and "pathlib.Path.glob()"
     methods, which call this function to implement pattern matching
     and globbing.

   在 3.13 版被加入.


Examples
========

Consider a directory containing the following files: "1.gif", "2.txt",
"card.gif" and a subdirectory "sub" which contains only the file
"3.txt".  "glob()" will produce the following results.  Notice how any
leading components of the path are preserved.

   >>> 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']

也參考:

  The "fnmatch" module offers shell-style filename (not path)
  expansion.

也參考: "pathlib" 模組提供高階路徑物件。
