Doc/library/glob.rst

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