glob — Unix style pathname pattern expansion¶

Source code:Lib/glob.py

Theglob module finds all the pathnames matching a specified patternaccording to the rules used by the Unix shell, although results are returned inarbitrary order. No tilde expansion is done, but*,?, and characterranges expressed with[] will be correctly matched. This is done by usingtheos.scandir() andfnmatch.fnmatch() functions in concert, andnot by actually invoking a subshell.

Note that files beginning with a dot (.) can only be matched bypatterns that also start with a dot,unlikefnmatch.fnmatch() orpathlib.Path.glob().(For tilde and shell variable expansion, useos.path.expanduser() andos.path.expandvars().)

For a literal match, wrap the meta-characters in brackets.For example,'[?]' matches the character'?'.

Theglob module defines the following functions:

glob.glob(pathname,*,root_dir=None,dir_fd=None,recursive=False,include_hidden=False)¶

Return a possibly empty list of path names that matchpathname, which must bea string containing a path specification.pathname can be either absolute(like/usr/src/Python-1.5/Makefile) or relative (like../../Tools/*/*.gif), and can contain shell-style wildcards. Brokensymlinks are included in the results (as in the shell). Whether or not theresults are sorted depends on the file system. If a file that satisfiesconditions is removed or added during the call of this function, whethera path name for that file will be included is unspecified.

Ifroot_dir is notNone, it should be apath-like objectspecifying the root directory for searching. It has the same effect onglob() as changing the current directory before calling it. Ifpathname is relative, the result will contain paths relative toroot_dir.

This function can supportpaths relative to directory descriptors with thedir_fd parameter.

Ifrecursive is true, the pattern “**” will match any files and zero ormore directories, subdirectories and symbolic links to directories. If thepattern is followed by anos.sep oros.altsep then files will notmatch.

Ifinclude_hidden is true, “**” pattern will match hidden directories.

Raises anauditing eventglob.glob with argumentspathname,recursive.

Raises anauditing eventglob.glob/2 with argumentspathname,recursive,root_dir,dir_fd.

Note

Using the “**” pattern in large directory trees may consumean inordinate amount of time.

Note

This function may return duplicate path names ifpathnamecontains multiple “**” patterns andrecursive is true.

Changed in version 3.5:Support for recursive globs using “**”.

Changed in version 3.10:Added theroot_dir anddir_fd parameters.

Changed in version 3.11:Added theinclude_hidden parameter.

glob.iglob(pathname,*,root_dir=None,dir_fd=None,recursive=False,include_hidden=False)¶

Return aniterator which yields the same values asglob()without actually storing them all simultaneously.

Raises anauditing eventglob.glob with argumentspathname,recursive.

Raises anauditing eventglob.glob/2 with argumentspathname,recursive,root_dir,dir_fd.

Note

This function may return duplicate path names ifpathnamecontains multiple “**” patterns andrecursive is true.

Changed in version 3.5:Support for recursive globs using “**”.

Changed in version 3.10:Added theroot_dir anddir_fd parameters.

Changed in version 3.11:Added theinclude_hidden parameter.

glob.escape(pathname)¶

Escape all special characters ('?','*' and'[').This is useful if you want to match an arbitrary literal string that mayhave special characters in it. Special characters in drive/UNCsharepoints are not escaped, e.g. on Windowsescape('//?/c:/Quovadis?.txt') returns'//?/c:/Quovadis[?].txt'.

Added in version 3.4.

glob.translate(pathname,*,recursive=False,include_hidden=False,seps=None)¶

Convert the given path specification to a regular expression for use withre.match(). The path specification can contain shell-style wildcards.

For example:

>>>importglob,re>>>>>>regex=glob.translate('**/*.txt',recursive=True,include_hidden=True)>>>regex'(?s:(?:.+/)?[^/]*\\.txt)\\z'>>>reobj=re.compile(regex)>>>reobj.match('foo/bar/baz.txt')<re.Match object; span=(0, 15), match='foo/bar/baz.txt'>

Path separators and segments are meaningful to this function, unlikefnmatch.translate(). By default wildcards do not match pathseparators, and* pattern segments match precisely one path segment.

Ifrecursive is true, the pattern segment “**” will match any numberof path segments.

Ifinclude_hidden is true, wildcards can match path segments that startwith a dot (.).

A sequence of path separators may be supplied to theseps argument. Ifnot given,os.sep andaltsep (if available) are used.

See also

pathlib.PurePath.full_match() andpathlib.Path.glob()methods, which call this function to implement pattern matching andglobbing.

Added in version 3.13.

>>>importglob>>>glob.glob('./[0-9].*')['./1.gif', './2.txt']>>>glob.glob('*.gif')['1.gif', 'card.gif']>>>glob.glob('?.gif')['1.gif']>>>glob.glob('**/*.txt',recursive=True)['2.txt', 'sub/3.txt']>>>glob.glob('./**/',recursive=True)['./', './sub/']

>>>importglob>>>glob.glob('*.gif')['card.gif']>>>glob.glob('.c*')['.card.gif']