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

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

`glob` モジュールは Unix シェルで使われているルールに従い指定されたパターンに一致するすべてのパス名を見つけ出します。返される結果の順序は不定です。チルダ展開は行われませんが、`*`, `?`, および `[]` で表現される文字範囲については正しくマッチされます。これは、関数 `os.scandir()` および `fnmatch.fnmatch()` を使用して行われており、実際にサブシェルを呼び出しているわけではありません。

ドット (`.`) で始まるファイルは、同じくドットで始まるパターンにのみマッチします。この動作は `fnmatch.fnmatch()` や `pathlib.Path.glob()` とは異なります。 (チルダやシェル変数の展開には、 `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` のような) 相対パスもどちらも指定可能で、シェル形式のワイルドカードを含めることもできます。参照先が存在しない、壊れたシンボリックリンクも (シェルの場合と同様に) 結果に含まれます。結果がソートされているかどうかはファイルシステムによります。条件を満たすファイルがこの関数の呼び出し中に追加または削除された場合、それらのファイルに対するパス名が結果に含まれるかどうかはの動作は不定です。

  root_dir が `None` でない場合、その値は検索のルートディレクトリを指定する path-like オブジェクト でなければなりません。これは `glob()` を呼び出す前にカレントディレクトリを変更したのと同じ効果を持ちます。 pathname が相対パスの場合、戻り値のリストは root_dir からの相対パスを含むことになります。

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

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

  include_hidden が真の場合、パターン "`**`" は隠しディレクトリにマッチします。

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

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

  注釈

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

  注釈

  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)

  実際には一度にすべてを格納せずに、`glob()` と同じ値を順に生成する イテレーター を返します。

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

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

  注釈

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

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

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

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

glob.escape(pathname)

  すべての特殊文字 (`'?'` 、 `'*'` 、 `'['`) をエスケープします。特殊文字を含んでいる可能性のある任意のリテラル文字列をマッチさせたいときに便利です。drive/UNC sharepoints の特殊文字はエスケープされません。たとえば 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)

  与えられたパスの仕様を `re.match()` で利用するための正規表現に変換します。シェル形式のワイルドカードを含めることもできます。

  例えば:

      >>> 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` モジュールは高水準のパスオブジェクトを提供します。