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