Doc/lib/libglob.tex

   1 \section{\module{glob} ---
   2          \UNIX{} style pathname pattern expansion}
   3
   4 \declaremodule{standard}{glob}
   5 \modulesynopsis{\UNIX\ shell style pathname pattern expansion.}
   6
   7
   8 The \module{glob} module finds all the pathnames matching a specified
   9 pattern according to the rules used by the \UNIX{} shell.  No tilde
  10 expansion is done, but \code{*}, \code{?}, and character ranges
  11 expressed with \code{[]} will be correctly matched.  This is done by
  12 using the \function{os.listdir()} and \function{fnmatch.fnmatch()}
  13 functions in concert, and not by actually invoking a subshell.  (For
  14 tilde and shell variable expansion, use \function{os.path.expanduser()}
  15 and \function{os.path.expandvars()}.)
  16 \index{filenames!pathname expansion}
  17
  18 \begin{funcdesc}{glob}{pathname}
  19 Return a possibly-empty list of path names that match \var{pathname},
  20 which must be a string containing a path specification.
  21 \var{pathname} can be either absolute (like
  22 \file{/usr/src/Python-1.5/Makefile}) or relative (like
  23 \file{../../Tools/*/*.gif}), and can contain shell-style wildcards.
  24 Broken symlinks are included in the results (as in the shell).
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{iglob}{pathname}
  28 Return an iterator which yields the same values as \function{glob()}
  29 without actually storing them all simultaneously.
  30 \versionadded{2.5}
  31 \end{funcdesc}
  32
  33 For example, consider a directory containing only the following files:
  34 \file{1.gif}, \file{2.txt}, and \file{card.gif}.  \function{glob()}
  35 will produce the following results.  Notice how any leading components
  36 of the path are preserved.
  37
  38 \begin{verbatim}
  39 >>> import glob
  40 >>> glob.glob('./[0-9].*')
  41 ['./1.gif', './2.txt']
  42 >>> glob.glob('*.gif')
  43 ['1.gif', 'card.gif']
  44 >>> glob.glob('?.gif')
  45 ['1.gif']
  46 \end{verbatim}
  47
  48
  49 \begin{seealso}
  50   \seemodule{fnmatch}{Shell-style filename (not path) expansion}
  51 \end{seealso}