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, *, root_dir=None, dir_fd=None, 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. If a file that satisfies 47 conditions is removed or added during the call of this function, whether 48 a path name for that file be included is unspecified. 49 50 If *root_dir* is not ``None``, it should be a :term:`path-like object` 51 specifying the root directory for searching. It has the same effect on 52 :func:`glob` as changing the current directory before calling it. If 53 *pathname* is relative, the result will contain paths relative to 54 *root_dir*. 55 56 This function can support :ref:`paths relative to directory descriptors 57 <dir_fd>` with the *dir_fd* parameter. 58 59 .. index:: 60 single: **; in glob-style wildcards 61 62 If *recursive* is true, the pattern "``**``" will match any files and zero or 63 more directories, subdirectories and symbolic links to directories. If the 64 pattern is followed by an :data:`os.sep` or :data:`os.altsep` then files will not 65 match. 66 67 .. audit-event:: glob.glob pathname,recursive glob.glob 68 .. audit-event:: glob.glob/2 pathname,recursive,root_dir,dir_fd glob.glob 69 70 .. note:: 71 Using the "``**``" pattern in large directory trees may consume 72 an inordinate amount of time. 73 74 .. versionchanged:: 3.5 75 Support for recursive globs using "``**``". 76 77 .. versionchanged:: 3.10 78 Added the *root_dir* and *dir_fd* parameters. 79 80 81.. function:: iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False) 82 83 Return an :term:`iterator` which yields the same values as :func:`glob` 84 without actually storing them all simultaneously. 85 86 .. audit-event:: glob.glob pathname,recursive glob.iglob 87 .. audit-event:: glob.glob/2 pathname,recursive,root_dir,dir_fd glob.iglob 88 89 .. versionchanged:: 3.5 90 Support for recursive globs using "``**``". 91 92 .. versionchanged:: 3.10 93 Added the *root_dir* and *dir_fd* parameters. 94 95 96.. function:: escape(pathname) 97 98 Escape all special characters (``'?'``, ``'*'`` and ``'['``). 99 This is useful if you want to match an arbitrary literal string that may 100 have special characters in it. Special characters in drive/UNC 101 sharepoints are not escaped, e.g. on Windows 102 ``escape('//?/c:/Quo vadis?.txt')`` returns ``'//?/c:/Quo vadis[?].txt'``. 103 104 .. versionadded:: 3.4 105 106 107For example, consider a directory containing the following files: 108:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub` 109which contains only the file :file:`3.txt`. :func:`glob` will produce 110the following results. Notice how any leading components of the path are 111preserved. :: 112 113 >>> import glob 114 >>> glob.glob('./[0-9].*') 115 ['./1.gif', './2.txt'] 116 >>> glob.glob('*.gif') 117 ['1.gif', 'card.gif'] 118 >>> glob.glob('?.gif') 119 ['1.gif'] 120 >>> glob.glob('**/*.txt', recursive=True) 121 ['2.txt', 'sub/3.txt'] 122 >>> glob.glob('./**/', recursive=True) 123 ['./', './sub/'] 124 125If the directory contains files starting with ``.`` they won't be matched by 126default. For example, consider a directory containing :file:`card.gif` and 127:file:`.card.gif`:: 128 129 >>> import glob 130 >>> glob.glob('*.gif') 131 ['card.gif'] 132 >>> glob.glob('.c*') 133 ['.card.gif'] 134 135.. seealso:: 136 137 Module :mod:`fnmatch` 138 Shell-style filename (not path) expansion 139