diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index b881a307647..75f67b9b0f0 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -16,8 +16,10 @@ according to the rules used by the Unix shell. No tilde expansion is done, but ``*``, ``?``, and character ranges expressed with ``[]`` will be correctly matched. This is done by using the :func:`os.listdir` and :func:`fnmatch.fnmatch` functions in concert, and not by actually invoking a -subshell. (For tilde and shell variable expansion, use -:func:`os.path.expanduser` and :func:`os.path.expandvars`.) +subshell. Note that unlike :func:`fnmatch.fnmatch`, :mod:`glob` treats +filenames beginning with a dot (``.``) as special cases. (For tilde and shell +variable expansion, use :func:`os.path.expanduser` and +:func:`os.path.expandvars`.) For a literal match, wrap the meta-characters in brackets. For example, ``'[?]'`` matches the character ``'?'``. @@ -52,6 +54,15 @@ preserved. :: >>> glob.glob('?.gif') ['1.gif'] +If the directory contains files starting with ``.`` they won't be matched by +default. For example, consider a directory containing :file:`card.gif` and +:file:`.card.gif`:: + + >>> import glob + >>> glob.glob('*.gif') + ['card.gif'] + >>> glob.glob('.c*') + ['.card.gif'] .. seealso:: diff --git a/Lib/glob.py b/Lib/glob.py index 0aee60561fa..f34534b53c4 100644 --- a/Lib/glob.py +++ b/Lib/glob.py @@ -18,7 +18,10 @@ __all__ = ["glob", "iglob"] def glob(pathname): """Return a list of paths matching a pathname pattern. - The pattern may contain simple shell-style wildcards a la fnmatch. + The pattern may contain simple shell-style wildcards a la + fnmatch. However, unlike fnmatch, filenames starting with a + dot are special cases that are not matched by '*' and '?' + patterns. """ return list(iglob(pathname)) @@ -26,7 +29,10 @@ def glob(pathname): def iglob(pathname): """Return an iterator which yields the paths matching a pathname pattern. - The pattern may contain simple shell-style wildcards a la fnmatch. + The pattern may contain simple shell-style wildcards a la + fnmatch. However, unlike fnmatch, filenames starting with a + dot are special cases that are not matched by '*' and '?' + patterns. """ if not has_magic(pathname): diff --git a/Misc/NEWS b/Misc/NEWS index 926593ae094..9f2a2bed90b 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -926,6 +926,9 @@ Tools/Demos Documentation ------------- +- Issue #16695: Document how glob handles filenames starting with a + dot. Initial patch by Jyrki Pulliainen. + - Issue #8890: Stop advertising an insecure practice by replacing uses of the /tmp directory with better alternatives in the documentation. Patch by Geoff Wilson.