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 |
Steve Dower | 60419a7 | 2019-06-24 08:42:54 -0700 | [diff] [blame] | 6 | import sys |
Guido van Rossum | 65a9620 | 1991-01-01 18:17:49 +0000 | [diff] [blame] | 7 | |
Serhiy Storchaka | 04b5700 | 2015-11-09 23:18:19 +0200 | [diff] [blame] | 8 | __all__ = ["glob", "iglob", "escape"] |
Guido van Rossum | bba77af | 1992-01-12 23:26:24 +0000 | [diff] [blame] | 9 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 10 | def glob(pathname, *, recursive=False): |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 11 | """Return a list of paths matching a pathname pattern. |
Guido van Rossum | ab096c9 | 1997-04-02 05:47:11 +0000 | [diff] [blame] | 12 | |
Petri Lehtinen | ee4a20b | 2013-02-23 19:53:03 +0100 | [diff] [blame] | 13 | The pattern may contain simple shell-style wildcards a la |
| 14 | fnmatch. However, unlike fnmatch, filenames starting with a |
| 15 | dot are special cases that are not matched by '*' and '?' |
| 16 | patterns. |
Guido van Rossum | ab096c9 | 1997-04-02 05:47:11 +0000 | [diff] [blame] | 17 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 18 | If recursive is true, the pattern '**' will match any files and |
| 19 | zero or more directories and subdirectories. |
Tim Peters | 07e99cb | 2001-01-14 23:47:14 +0000 | [diff] [blame] | 20 | """ |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 21 | return list(iglob(pathname, recursive=recursive)) |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 22 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 23 | def iglob(pathname, *, recursive=False): |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 24 | """Return an iterator which yields the paths matching a pathname pattern. |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 25 | |
Petri Lehtinen | ee4a20b | 2013-02-23 19:53:03 +0100 | [diff] [blame] | 26 | The pattern may contain simple shell-style wildcards a la |
| 27 | fnmatch. However, unlike fnmatch, filenames starting with a |
| 28 | dot are special cases that are not matched by '*' and '?' |
| 29 | patterns. |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 30 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 31 | If recursive is true, the pattern '**' will match any files and |
| 32 | zero or more directories and subdirectories. |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 33 | """ |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 34 | it = _iglob(pathname, recursive, False) |
Serhiy Storchaka | 735b790 | 2015-11-09 23:12:07 +0200 | [diff] [blame] | 35 | if recursive and _isrecursive(pathname): |
| 36 | s = next(it) # skip empty string |
| 37 | assert not s |
| 38 | return it |
| 39 | |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 40 | def _iglob(pathname, recursive, dironly): |
Steve Dower | 60419a7 | 2019-06-24 08:42:54 -0700 | [diff] [blame] | 41 | sys.audit("glob.glob", pathname, recursive) |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 42 | dirname, basename = os.path.split(pathname) |
Serhiy Storchaka | 6f20170 | 2014-08-12 12:55:12 +0300 | [diff] [blame] | 43 | if not has_magic(pathname): |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 44 | assert not dironly |
Serhiy Storchaka | 6f20170 | 2014-08-12 12:55:12 +0300 | [diff] [blame] | 45 | if basename: |
| 46 | if os.path.lexists(pathname): |
| 47 | yield pathname |
| 48 | else: |
| 49 | # Patterns ending with a slash should match only directories |
| 50 | if os.path.isdir(dirname): |
| 51 | yield pathname |
| 52 | return |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 53 | if not dirname: |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 54 | if recursive and _isrecursive(basename): |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 55 | yield from _glob2(dirname, basename, dironly) |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 56 | else: |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 57 | yield from _glob1(dirname, basename, dironly) |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 58 | return |
Antoine Pitrou | 3d068b2 | 2012-12-16 13:49:37 +0100 | [diff] [blame] | 59 | # `os.path.split()` returns the argument itself as a dirname if it is a |
| 60 | # drive or UNC path. Prevent an infinite recursion if a drive or UNC path |
| 61 | # contains magic characters (i.e. r'\\?\C:'). |
| 62 | if dirname != pathname and has_magic(dirname): |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 63 | dirs = _iglob(dirname, recursive, True) |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 64 | else: |
| 65 | dirs = [dirname] |
| 66 | if has_magic(basename): |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 67 | if recursive and _isrecursive(basename): |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 68 | glob_in_dir = _glob2 |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 69 | else: |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 70 | glob_in_dir = _glob1 |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 71 | else: |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 72 | glob_in_dir = _glob0 |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 73 | for dirname in dirs: |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 74 | for name in glob_in_dir(dirname, basename, dironly): |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 75 | yield os.path.join(dirname, name) |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 76 | |
| 77 | # These 2 helper functions non-recursively glob inside a literal directory. |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 78 | # They return a list of basenames. _glob1 accepts a pattern while _glob0 |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 79 | # 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] | 80 | |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 81 | def _glob1(dirname, pattern, dironly): |
| 82 | names = list(_iterdir(dirname, dironly)) |
Hynek Schlawack | e26568f | 2012-12-27 10:10:11 +0100 | [diff] [blame] | 83 | if not _ishidden(pattern): |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 84 | names = (x for x in names if not _ishidden(x)) |
Guido van Rossum | d8faa36 | 2007-04-27 19:54:29 +0000 | [diff] [blame] | 85 | return fnmatch.filter(names, pattern) |
Guido van Rossum | 65a9620 | 1991-01-01 18:17:49 +0000 | [diff] [blame] | 86 | |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 87 | def _glob0(dirname, basename, dironly): |
Antoine Pitrou | 5461558 | 2012-12-16 16:03:01 +0100 | [diff] [blame] | 88 | if not basename: |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 89 | # `os.path.split()` returns an empty basename for paths ending with a |
| 90 | # directory separator. 'q*x/' should match only directories. |
Thomas Wouters | 49fd7fa | 2006-04-21 10:40:58 +0000 | [diff] [blame] | 91 | if os.path.isdir(dirname): |
Johannes Gijsbers | 836f543 | 2005-01-08 13:13:19 +0000 | [diff] [blame] | 92 | return [basename] |
| 93 | else: |
| 94 | if os.path.lexists(os.path.join(dirname, basename)): |
| 95 | return [basename] |
| 96 | return [] |
| 97 | |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 98 | # Following functions are not public but can be used by third-party code. |
| 99 | |
| 100 | def glob0(dirname, pattern): |
| 101 | return _glob0(dirname, pattern, False) |
| 102 | |
| 103 | def glob1(dirname, pattern): |
| 104 | return _glob1(dirname, pattern, False) |
| 105 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 106 | # This helper function recursively yields relative pathnames inside a literal |
| 107 | # directory. |
| 108 | |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 109 | def _glob2(dirname, pattern, dironly): |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 110 | assert _isrecursive(pattern) |
Serhiy Storchaka | 735b790 | 2015-11-09 23:12:07 +0200 | [diff] [blame] | 111 | yield pattern[:0] |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 112 | yield from _rlistdir(dirname, dironly) |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 113 | |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 114 | # If dironly is false, yields all file names inside a directory. |
| 115 | # If dironly is true, yields only directory names. |
| 116 | def _iterdir(dirname, dironly): |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 117 | if not dirname: |
| 118 | if isinstance(dirname, bytes): |
| 119 | dirname = bytes(os.curdir, 'ASCII') |
| 120 | else: |
| 121 | dirname = os.curdir |
| 122 | try: |
Serhiy Storchaka | 3ae4155 | 2016-10-05 23:17:10 +0300 | [diff] [blame] | 123 | with os.scandir(dirname) as it: |
| 124 | for entry in it: |
| 125 | try: |
| 126 | if not dironly or entry.is_dir(): |
| 127 | yield entry.name |
| 128 | except OSError: |
| 129 | pass |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 130 | except OSError: |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 131 | return |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 132 | |
| 133 | # Recursively yields relative pathnames inside a literal directory. |
| 134 | def _rlistdir(dirname, dironly): |
| 135 | names = list(_iterdir(dirname, dironly)) |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 136 | for x in names: |
| 137 | if not _ishidden(x): |
| 138 | yield x |
| 139 | path = os.path.join(dirname, x) if dirname else x |
Serhiy Storchaka | 28ab634 | 2016-09-06 22:33:41 +0300 | [diff] [blame] | 140 | for y in _rlistdir(path, dironly): |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 141 | yield os.path.join(x, y) |
| 142 | |
Guido van Rossum | c2ef5c2 | 1992-01-12 23:32:11 +0000 | [diff] [blame] | 143 | |
Serhiy Storchaka | fd32fff | 2013-11-18 13:06:43 +0200 | [diff] [blame] | 144 | magic_check = re.compile('([*?[])') |
| 145 | magic_check_bytes = re.compile(b'([*?[])') |
Tim Golden | 9b3fb0c | 2012-11-06 15:33:30 +0000 | [diff] [blame] | 146 | |
Guido van Rossum | 65a9620 | 1991-01-01 18:17:49 +0000 | [diff] [blame] | 147 | def has_magic(s): |
Guido van Rossum | f0af3e3 | 2008-10-02 18:55:37 +0000 | [diff] [blame] | 148 | if isinstance(s, bytes): |
| 149 | match = magic_check_bytes.search(s) |
| 150 | else: |
| 151 | match = magic_check.search(s) |
| 152 | return match is not None |
Hynek Schlawack | e26568f | 2012-12-27 10:10:11 +0100 | [diff] [blame] | 153 | |
| 154 | def _ishidden(path): |
| 155 | return path[0] in ('.', b'.'[0]) |
Serhiy Storchaka | fd32fff | 2013-11-18 13:06:43 +0200 | [diff] [blame] | 156 | |
Serhiy Storchaka | c2edcdd | 2014-09-11 12:17:37 +0300 | [diff] [blame] | 157 | def _isrecursive(pattern): |
| 158 | if isinstance(pattern, bytes): |
| 159 | return pattern == b'**' |
| 160 | else: |
| 161 | return pattern == '**' |
| 162 | |
Serhiy Storchaka | fd32fff | 2013-11-18 13:06:43 +0200 | [diff] [blame] | 163 | def escape(pathname): |
| 164 | """Escape all special characters. |
| 165 | """ |
| 166 | # Escaping is done by wrapping any of "*?[" between square brackets. |
| 167 | # Metacharacters do not work in the drive part and shouldn't be escaped. |
| 168 | drive, pathname = os.path.splitdrive(pathname) |
| 169 | if isinstance(pathname, bytes): |
| 170 | pathname = magic_check_bytes.sub(br'[\1]', pathname) |
| 171 | else: |
| 172 | pathname = magic_check.sub(r'[\1]', pathname) |
| 173 | return drive + pathname |