1:mod:`glob` --- Unix style pathname pattern expansion 2===================================================== 3 4.. module:: glob 5 :synopsis: Unix shell style pathname pattern expansion. 6 7**Source code:** :source:`Lib/glob.py` 8 9.. index:: single: filenames; pathname expansion 10 11-------------- 12 13.. index:: 14 single: * (asterisk); in glob-style wildcards 15 single: ? (question mark); in glob-style wildcards 16 single: [] (square brackets); in glob-style wildcards 17 single: ! (exclamation); in glob-style wildcards 18 single: - (minus); in glob-style wildcards 19 single: . (dot); in glob-style wildcards 20 21The :mod:`glob` module finds all the pathnames matching a specified pattern 22according to the rules used by the Unix shell, although results are returned in 23arbitrary order. No tilde expansion is done, but ``*``, ``?``, and character 24ranges expressed with ``[]`` will be correctly matched. This is done by using 25the :func:`os.scandir` and :func:`fnmatch.fnmatch` functions in concert, and 26not by actually invoking a subshell. Note that unlike :func:`fnmatch.fnmatch`, 27:mod:`glob` treats filenames beginning with a dot (``.``) as special cases. 28(For tilde and shell variable expansion, use :func:`os.path.expanduser` and 29:func:`os.path.expandvars`.) 30 31For a literal match, wrap the meta-characters in brackets. 32For example, ``'[?]'`` matches the character ``'?'``. 33 34 35.. seealso:: 36 The :mod:`pathlib` module offers high-level path objects. 37 38 39.. function:: glob(pathname, *, recursive=False) 40 41 Return a possibly-empty list of path names that match *pathname*, which must be 42 a string containing a path specification. *pathname* can be either absolute 43 (like :file:`/usr/src/Python-1.5/Makefile`) or relative (like 44 :file:`../../Tools/\*/\*.gif`), and can contain shell-style wildcards. Broken 45 symlinks are included in the results (as in the shell). Whether or not the 46 results are sorted depends on the file system. 47 48 .. index:: 49 single: **; in glob-style wildcards 50 51 If *recursive* is true, the pattern "``**``" will match any files and zero or 52 more directories, subdirectories and symbolic links to directories. If the 53 pattern is followed by an :data:`os.sep` or :data:`os.altsep` then files will not 54 match. 55 56 .. audit-event:: glob.glob pathname,recursive glob.glob 57 58 .. note:: 59 Using the "``**``" pattern in large directory trees may consume 60 an inordinate amount of time. 61 62 .. versionchanged:: 3.5 63 Support for recursive globs using "``**``". 64 65 66.. function:: iglob(pathname, *, recursive=False) 67 68 Return an :term:`iterator` which yields the same values as :func:`glob` 69 without actually storing them all simultaneously. 70 71 .. audit-event:: glob.glob pathname,recursive glob.iglob 72 73 74.. function:: escape(pathname) 75 76 Escape all special characters (``'?'``, ``'*'`` and ``'['``). 77 This is useful if you want to match an arbitrary literal string that may 78 have special characters in it. Special characters in drive/UNC 79 sharepoints are not escaped, e.g. on Windows 80 ``escape('//?/c:/Quo vadis?.txt')`` returns ``'//?/c:/Quo vadis[?].txt'``. 81 82 .. versionadded:: 3.4 83 84 85For example, consider a directory containing the following files: 86:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub` 87which contains only the file :file:`3.txt`. :func:`glob` will produce 88the following results. Notice how any leading components of the path are 89preserved. :: 90 91 >>> import glob 92 >>> glob.glob('./[0-9].*') 93 ['./1.gif', './2.txt'] 94 >>> glob.glob('*.gif') 95 ['1.gif', 'card.gif'] 96 >>> glob.glob('?.gif') 97 ['1.gif'] 98 >>> glob.glob('**/*.txt', recursive=True) 99 ['2.txt', 'sub/3.txt'] 100 >>> glob.glob('./**/', recursive=True) 101 ['./', './sub/'] 102 103If the directory contains files starting with ``.`` they won't be matched by 104default. For example, consider a directory containing :file:`card.gif` and 105:file:`.card.gif`:: 106 107 >>> import glob 108 >>> glob.glob('*.gif') 109 ['card.gif'] 110 >>> glob.glob('.c*') 111 ['.card.gif'] 112 113.. seealso:: 114 115 Module :mod:`fnmatch` 116 Shell-style filename (not path) expansion 117 118
