# `glob` --- Unix 形式のパス名のパターン展開

ソースコード: Lib/glob.py

The `glob` module finds pathnames using pattern matching rules similar to the Unix shell. No tilde expansion is done, but `*`, `?`, and character ranges expressed with `[]` will be correctly matched. This is done by using the `os.scandir()` and `fnmatch.fnmatch()` functions in concert, and not by actually invoking a subshell.

注釈

The pathnames are returned in no particular order. If you need a specific order, sort the results.

By default, files beginning with a dot (`.`) can only be matched by patterns that also start with a dot, unlike `fnmatch.fnmatch()` or `pathlib.Path.glob()`. For tilde and shell variable expansion, use `os.path.expanduser()` and `os.path.expandvars()`.

リテラルにマッチさせるには、メタ文字を括弧に入れてください。例えば、`'[?]'` は文字 `'?'` にマッチします。

The `glob` module defines the following functions:

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

  パスの仕様を含む文字列 pathname にマッチするパス名のリストを返します。戻り値のリストは空になる可能性があります。 pathname は (`/usr/src/Python-1.5/Makefile` のような) 絶対パスも、 (`../../Tools/*/*.gif` のような) 相対パスもどちらも指定可能で、シェル形式のワイルドカードを含めることもできます。参照先が存在しない、壊れたシンボリックリンクも (シェルの場合と同様に) 結果に含まれます。結果がソートされているかどうかはファイルシステムによります。条件を満たすファイルがこの関数の呼び出し中に追加または削除された場合、それらのファイルに対するパス名が結果に含まれるかどうかはの動作は不定です。

  If root_dir is not `None`, it should be a path-like object specifying the root directory for searching. It has the same effect on `glob()` as changing the current directory before calling it. If pathname is relative, the result will contain paths relative to root_dir.

  この関数は dir_fd パラメタで ディレクトリ記述子への相対パス をサポートしています。

  recursive が真の場合、パターン "`**`" はあらゆるファイルや0個以上のディレクトリ、サブディレクトリおよびディレクトリへのシンボリックリンクにマッチします。パターンの末尾が `os.sep` または `os.altsep` の場合、ファイルは一致しません。

  If include_hidden is true, wildcards can match path segments that begin with a dot (`.`).

  引数 `pathname`, `recursive` を指定して 監査イベント `glob.glob` を送出します。

  引数 `pathname`, `recursive`, `root_dir`, `dir_fd` を指定して 監査イベント `glob.glob/2` を送出します。

  注釈

  パターン "`**`" を大きなディレクトリツリーで使用するととてつもなく時間がかかるかもしれません。

  注釈

  pathname が複数の "`**`" パターンを含み、かつ recursive が真の場合、この関数は同じパスを重複して返す可能性があります。

  注釈

  Any `OSError` exceptions raised from scanning the filesystem are suppressed. This includes `PermissionError` when accessing directories without read permission.

  バージョン 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()` と同じ値を順に生成する イテレーター を返します。

  引数 `pathname`, `recursive` を指定して 監査イベント `glob.glob` を送出します。

  引数 `pathname`, `recursive`, `root_dir`, `dir_fd` を指定して 監査イベント `glob.glob/2` を送出します。

  注釈

  pathname が複数の "`**`" パターンを含み、かつ recursive が真の場合、この関数は同じパスを重複して返す可能性があります。

  注釈

  Any `OSError` exceptions raised from scanning the filesystem are suppressed. This includes `PermissionError` when accessing directories without read permission.

  バージョン 3.5 で変更: "`**`" を使った再帰的な glob がサポートされました。

  バージョン 3.10 で変更: root_dir と dir_fd 引数が追加されました。

  バージョン 3.11 で変更: include_hidden パラメータが追加されました。

glob.escape(pathname)

  Escape all special characters (`'?'`, `'*'` and `'['`). This is useful if you want to match an arbitrary literal string that may have special characters in it. Special characters in drive/UNC sharepoints are not escaped, for example on Windows `escape('//?/c:/Quo vadis?.txt')` returns `'//?/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.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'>

  `fnmatch.translate()` と違って、この関数ではパスの要素を区切るセパレータとセグメントには意味があります。デフォルトでは、ワイルドカードはパスのセパレータにはマッチしません。また `*` パターンのセグメントは厳密に単一のパスのセグメントにマッチします。

  recursive が真の場合、パターンセグメント "`**`" は任意の数のパスセグメントにマッチします。

  include_hidden が真の場合、ワイルドカードはドット (`.`) で始まるパスセグメントにもマッチします。

  パスの要素を区切るセパレータのシーケンスを seps 引数に渡すことができます。渡さない場合は `os.sep` と (もしあれば) `altsep` が使われます。

  参考

  `pathlib.PurePath.full_match()` と `pathlib.Path.glob()` の2つのメソッドは、それぞれパターンマッチと glob 相当の操作を実装するためにこの関数を呼んでいます。

  Added in version 3.13.

## 使用例

次のファイルを含むディレクトリを考えます: `1.gif`, `2.txt`, `card.gif` および:file: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` モジュールは、シェル形式の (パスではなく) ファイル名の展開機能を提供します。

参考

`pathlib` モジュールは高水準のパスオブジェクトを提供します。