"glob" --- Unix style pathname pattern expansion
************************************************

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

======================================================================

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

ドット (".") で始まるファイルは、同じくドットで始まるパターンにのみマ
ッチします。この動作は "fnmatch.fnmatch()" や "pathlib.Path.glob()" と
は異なります。 (チルダやシェル変数の展開には、 "os.path.expanduser()"
と "os.path.expandvars()" を使ってください。)

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

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

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

   Return a possibly empty list of path names that match *pathname*,
   which must be a string containing a path specification. *pathname*
   can be either absolute (like "/usr/src/Python-1.5/Makefile") or
   relative (like "../../Tools/*/*.gif"), and can contain shell-style
   wildcards. Broken symlinks are included in the results (as in the
   shell). Whether or not the results are sorted depends on the file
   system.  If a file that satisfies conditions is removed or added
   during the call of this function, whether a path name for that file
   be included is unspecified.

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

   注釈:

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

   バージョン 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" を送出します。

   バージョン 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'" を返します。

   バージョン 3.4 で追加.

For example, 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']

参考:

  Module "fnmatch"
     Shell-style filename (not path) expansion
