Guido van Rossum | ab096c9 | 1997-04-02 05:47:11 +0000 | [diff] [blame] | 1 | """Filename globbing utility.""" |
Guido van Rossum | 65a9620 | 1991-01-01 18:17:49 +0000 | [diff] [blame] | 2 | |
Guido van Rossum | bba77af | 1992-01-12 23:26:24 +0000 | [diff] [blame] | 3 | import os |
Guido van Rossum | 9694fca | 1997-10-22 21:00:49 +0000 | [diff] [blame] | 4 | import re |
Guido van Rossum | d8faa36 | 2007-04-27 19:54:29 +0000 | [diff] [blame] | 5 | import fnmatch |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 6 | import itertools |
| 7 | import stat |
Steve Dower | 60419a7 | 2019-06-24 08:42:54 -0700 | [diff] [blame] | 8 | import sys |
Guido van Rossum | 65a9620 | 1991-01-01 18:17:49 +0000 | [diff] [blame] | 9 | |
Serhiy Storchaka | 04b5700 | 2015-11-09 23:18:19 +0200 | [diff] [blame] | 10 | __all__ = ["glob", "iglob", "escape"] |
Guido van Rossum | bba77af | 1992-01-12 23:26:24 +0000 | [diff] [blame] | 11 | |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 12 | def glob(pathname, *, root_dir=None, dir_fd=None, recursive=False): |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 13 | """Return a list of paths matching a pathname pattern. |
Guido van Rossum | ab096c9 | 1997-04-02 05:47:11 +0000 | [diff] [blame] | 14 | |
Petri Lehtinen | ee4a20b | 2013-02-23 19:53:03 +0100 | [diff] [blame] | 15 | The pattern may contain simple shell-style wildcards a la |
| 16 | fnmatch. However, unlike fnmatch, filenames starting with a |
| 17 | dot are special cases that are not matched by '*' and '?' |
| 18 | patterns. |
Guido van Rossum | ab096c9 | 1997-04-02 05:47:11 +0000 | [diff] [blame] | 19 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 20 | If recursive is true, the pattern '**' will match any files and |
| 21 | zero or more directories and subdirectories. |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 22 | """ |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 23 | return list(iglob(pathname, root_dir=root_dir, dir_fd=dir_fd, recursive=recursive)) |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 24 | |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 25 | def iglob(pathname, *, root_dir=None, dir_fd=None, recursive=False): |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 26 | """Return an iterator which yields the paths matching a pathname pattern. |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 27 | |
Petri Lehtinen | ee4a20b | 2013-02-23 19:53:03 +0100 | [diff] [blame] | 28 | The pattern may contain simple shell-style wildcards a la |
| 29 | fnmatch. However, unlike fnmatch, filenames starting with a |
| 30 | dot are special cases that are not matched by '*' and '?' |
| 31 | patterns. |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 32 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 33 | If recursive is true, the pattern '**' will match any files and |
| 34 | zero or more directories and subdirectories. |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 35 | """ |
Serhiy Storchaka | 1d34699 | 2020-10-20 19:45:38 +0300 | [diff] [blame] | 36 | sys.audit("glob.glob", pathname, recursive) |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 37 | if root_dir is not None: |
| 38 | root_dir = os.fspath(root_dir) |
| 39 | else: |
| 40 | root_dir = pathname[:0] |
| 41 | it = _iglob(pathname, root_dir, dir_fd, recursive, False) |
| 42 | if not pathname or recursive and _isrecursive(pathname[:2]): |
| 43 | try: |
| 44 | s = next(it) # skip empty string |
| 45 | if s: |
| 46 | it = itertools.chain((s,), it) |
| 47 | except StopIteration: |
| 48 | pass |
Serhiy Storchaka | 735b790 | 2015-11-09 23:12:07 +0200 | [diff] [blame] | 49 | return it |
| 50 | |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 51 | def _iglob(pathname, root_dir, dir_fd, recursive, dironly): |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 52 | dirname, basename = os.path.split(pathname) |
Serhiy Storchaka | 6f20170 | 2014-08-12 12:55:12 +0300 | [diff] [blame] | 53 | if not has_magic(pathname): |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 54 | assert not dironly |
Serhiy Storchaka | 6f20170 | 2014-08-12 12:55:12 +0300 | [diff] [blame] | 55 | if basename: |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 56 | if _lexists(_join(root_dir, pathname), dir_fd): |
Serhiy Storchaka | 6f20170 | 2014-08-12 12:55:12 +0300 | [diff] [blame] | 57 | yield pathname |
| 58 | else: |
| 59 | # Patterns ending with a slash should match only directories |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 60 | if _isdir(_join(root_dir, dirname), dir_fd): |
Serhiy Storchaka | 6f20170 | 2014-08-12 12:55:12 +0300 | [diff] [blame] | 61 | yield pathname |
| 62 | return |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 63 | if not dirname: |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 64 | if recursive and _isrecursive(basename): |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 65 | yield from _glob2(root_dir, basename, dir_fd, dironly) |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 66 | else: |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 67 | yield from _glob1(root_dir, basename, dir_fd, dironly) |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 68 | return |
Antoine Pitrou | 3d068b2 | 2012-12-16 13:49:37 +0100 | [diff] [blame] | 69 | # `os.path.split()` returns the argument itself as a dirname if it is a |
| 70 | # drive or UNC path. Prevent an infinite recursion if a drive or UNC path |
| 71 | # contains magic characters (i.e. r'\\?\C:'). |
| 72 | if dirname != pathname and has_magic(dirname): |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 73 | dirs = _iglob(dirname, root_dir, dir_fd, recursive, True) |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 74 | else: |
| 75 | dirs = [dirname] |
| 76 | if has_magic(basename): |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 77 | if recursive and _isrecursive(basename): |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 78 | glob_in_dir = _glob2 |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 79 | else: |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 80 | glob_in_dir = _glob1 |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 81 | else: |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 82 | glob_in_dir = _glob0 |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 83 | for dirname in dirs: |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 84 | for name in glob_in_dir(_join(root_dir, dirname), basename, dir_fd, dironly): |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 85 | yield os.path.join(dirname, name) |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 86 | |
| 87 | # These 2 helper functions non-recursively glob inside a literal directory. |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 88 | # They return a list of basenames. _glob1 accepts a pattern while _glob0 |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 89 | # takes a literal basename (so it only has to check for its existence). |
Guido van Rossum | 65a9620 | 1991-01-01 18:17:49 +0000 | [diff] [blame] | 90 | |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 91 | def _glob1(dirname, pattern, dir_fd, dironly): |
| 92 | names = list(_iterdir(dirname, dir_fd, dironly)) |
Hynek Schlawack | e26568f | 2012-12-27 10:10:11 +0100 | [diff] [blame] | 93 | if not _ishidden(pattern): |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 94 | names = (x for x in names if not _ishidden(x)) |
Guido van Rossum | d8faa36 | 2007-04-27 19:54:29 +0000 | [diff] [blame] | 95 | return fnmatch.filter(names, pattern) |
Guido van Rossum | 65a9620 | 1991-01-01 18:17:49 +0000 | [diff] [blame] | 96 | |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 97 | def _glob0(dirname, basename, dir_fd, dironly): |
| 98 | if basename: |
| 99 | if _lexists(_join(dirname, basename), dir_fd): |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 100 | return [basename] |
| 101 | else: |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 102 | # `os.path.split()` returns an empty basename for paths ending with a |
| 103 | # directory separator. 'q*x/' should match only directories. |
| 104 | if _isdir(dirname, dir_fd): |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 105 | return [basename] |
| 106 | return [] |
| 107 | |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 108 | # Following functions are not public but can be used by third-party code. |
| 109 | |
| 110 | def glob0(dirname, pattern): |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 111 | return _glob0(dirname, pattern, None, False) |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 112 | |
| 113 | def glob1(dirname, pattern): |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 114 | return _glob1(dirname, pattern, None, False) |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 115 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 116 | # This helper function recursively yields relative pathnames inside a literal |
| 117 | # directory. |
| 118 | |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 119 | def _glob2(dirname, pattern, dir_fd, dironly): |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 120 | assert _isrecursive(pattern) |
Serhiy Storchaka | 735b790 | 2015-11-09 23:12:07 +0200 | [diff] [blame] | 121 | yield pattern[:0] |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 122 | yield from _rlistdir(dirname, dir_fd, dironly) |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 123 | |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 124 | # If dironly is false, yields all file names inside a directory. |
| 125 | # If dironly is true, yields only directory names. |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 126 | def _iterdir(dirname, dir_fd, dironly): |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 127 | try: |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 128 | fd = None |
| 129 | fsencode = None |
| 130 | if dir_fd is not None: |
| 131 | if dirname: |
| 132 | fd = arg = os.open(dirname, _dir_open_flags, dir_fd=dir_fd) |
| 133 | else: |
| 134 | arg = dir_fd |
| 135 | if isinstance(dirname, bytes): |
| 136 | fsencode = os.fsencode |
| 137 | elif dirname: |
| 138 | arg = dirname |
| 139 | elif isinstance(dirname, bytes): |
| 140 | arg = bytes(os.curdir, 'ASCII') |
| 141 | else: |
| 142 | arg = os.curdir |
| 143 | try: |
| 144 | with os.scandir(arg) as it: |
| 145 | for entry in it: |
| 146 | try: |
| 147 | if not dironly or entry.is_dir(): |
| 148 | if fsencode is not None: |
| 149 | yield fsencode(entry.name) |
| 150 | else: |
| 151 | yield entry.name |
| 152 | except OSError: |
| 153 | pass |
| 154 | finally: |
| 155 | if fd is not None: |
| 156 | os.close(fd) |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 157 | except OSError: |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 158 | return |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 159 | |
| 160 | # Recursively yields relative pathnames inside a literal directory. |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 161 | def _rlistdir(dirname, dir_fd, dironly): |
| 162 | names = list(_iterdir(dirname, dir_fd, dironly)) |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 163 | for x in names: |
| 164 | if not _ishidden(x): |
| 165 | yield x |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 166 | path = _join(dirname, x) if dirname else x |
| 167 | for y in _rlistdir(path, dir_fd, dironly): |
| 168 | yield _join(x, y) |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 169 | |
Guido van Rossum | c2ef5c2 | 1992-01-12 23:32:11 +0000 | [diff] [blame] | 170 | |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 171 | def _lexists(pathname, dir_fd): |
| 172 | # Same as os.path.lexists(), but with dir_fd |
| 173 | if dir_fd is None: |
| 174 | return os.path.lexists(pathname) |
| 175 | try: |
| 176 | os.lstat(pathname, dir_fd=dir_fd) |
| 177 | except (OSError, ValueError): |
| 178 | return False |
| 179 | else: |
| 180 | return True |
| 181 | |
| 182 | def _isdir(pathname, dir_fd): |
| 183 | # Same as os.path.isdir(), but with dir_fd |
| 184 | if dir_fd is None: |
| 185 | return os.path.isdir(pathname) |
| 186 | try: |
| 187 | st = os.stat(pathname, dir_fd=dir_fd) |
| 188 | except (OSError, ValueError): |
| 189 | return False |
| 190 | else: |
| 191 | return stat.S_ISDIR(st.st_mode) |
| 192 | |
| 193 | def _join(dirname, basename): |
| 194 | # It is common if dirname or basename is empty |
| 195 | if not dirname or not basename: |
| 196 | return dirname or basename |
| 197 | return os.path.join(dirname, basename) |
| 198 | |
Serhiy Storchaka | fd32fff | 2013-11-18 13:06:43 +0200 | [diff] [blame] | 199 | magic_check = re.compile('([*?[])') |
| 200 | magic_check_bytes = re.compile(b'([*?[])') |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 201 | |
Guido van Rossum | 65a9620 | 1991-01-01 18:17:49 +0000 | [diff] [blame] | 202 | def has_magic(s): |
Guido van Rossum | f0af3e3 | 2008-10-02 18:55:37 +0000 | [diff] [blame] | 203 | if isinstance(s, bytes): |
| 204 | match = magic_check_bytes.search(s) |
| 205 | else: |
| 206 | match = magic_check.search(s) |
| 207 | return match is not None |
Hynek Schlawack | e26568f | 2012-12-27 10:10:11 +0100 | [diff] [blame] | 208 | |
| 209 | def _ishidden(path): |
| 210 | return path[0] in ('.', b'.'[0]) |
Serhiy Storchaka | fd32fff | 2013-11-18 13:06:43 +0200 | [diff] [blame] | 211 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 212 | def _isrecursive(pattern): |
| 213 | if isinstance(pattern, bytes): |
| 214 | return pattern == b'**' |
| 215 | else: |
| 216 | return pattern == '**' |
| 217 | |
Serhiy Storchaka | fd32fff | 2013-11-18 13:06:43 +0200 | [diff] [blame] | 218 | def escape(pathname): |
| 219 | """Escape all special characters. |
| 220 | """ |
| 221 | # Escaping is done by wrapping any of "*?[" between square brackets. |
| 222 | # Metacharacters do not work in the drive part and shouldn't be escaped. |
| 223 | drive, pathname = os.path.splitdrive(pathname) |
| 224 | if isinstance(pathname, bytes): |
| 225 | pathname = magic_check_bytes.sub(br'[\1]', pathname) |
| 226 | else: |
| 227 | pathname = magic_check.sub(r'[\1]', pathname) |
| 228 | return drive + pathname |
Serhiy Storchaka | 8a64cea | 2020-06-18 22:08:27 +0300 | [diff] [blame] | 229 | |
| 230 | |
| 231 | _dir_open_flags = os.O_RDONLY | getattr(os, 'O_DIRECTORY', 0) |