"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 object* でなければなりません。 "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* が真
     の場合、この関数は同じパスを重複して返す可能性があります。

   注釈:

     ファイルシステムの走査で発生した "OSError" 例外はすべて抑制されま
     す。 これには、読み取り権限のないディレクトリへのアクセス時に発生
     する "PermissionError" も含まれます。

   バージョン 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* が真
     の場合、この関数は同じパスを重複して返す可能性があります。

   注釈:

     ファイルシステムの走査で発生した "OSError" 例外はすべて抑制されま
     す。 これには、読み取り権限のないディレクトリへのアクセス時に発生
     する "PermissionError" も含まれます。

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

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

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

glob.escape(pathname)

   すべての特殊文字 ("'?'"、"'*'"、"'['") をエスケープします。 特殊文
   字を含む可能性がある任意の文字列に、そのままマッチさせたい場合に便
   利です。 ドライブ名や UNC 共有ポイントの特殊文字はエスケープしませ
   ん。 例えば 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.prefixmatch()" で使う正規表現に変換し
   ます。 パスのパターンにはシェル形式のワイルドカードを含められます。

   例えば:

   >>> import glob, re
   >>>
   >>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True)
   >>> regex
   '(?s:(?:.+/)?[^/]*\\.txt)\\z'
   >>> reobj = re.compile(regex)
   >>> reobj.prefixmatch('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"
および "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" モジュールは高水準のパスオブジェクトを提供します。
