# `glob` --- Unix 風格的路徑名稱模式擴展

原始碼：Lib/glob.py

`glob` 模組使用類似於 Unix shell 的模式匹配規則來尋找路徑名稱。不會進行波浪號擴展 (tilde expansion) ，但 `*`、`?` 和使用 `[]` 表達的字元範圍將會被正確匹配。這是透過結合使用 `os.scandir()` 和 `fnmatch.fnmatch()` 函式來完成的，而沒有實際呼叫 subshell。

備註

路徑名稱不會以特定順序回傳。如果你需要特定的順序，請對結果進行排序。

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

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

`glob` 模組定義了以下函式：

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.

  舉例來說：

      >>> 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 版被加入.

## 範例

例如，在一個包含以下檔案的目錄：`1.gif`、`2.txt`、`card.gif`，和一個僅包含 `3.txt` 檔案的子目錄 `sub`，`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` 模組提供高階路徑物件。