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

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

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

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

  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` を送出します。

  注釈

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

  注釈

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

  引数 `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)

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

  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.

  Added in version 3.13.

## 使用例

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