Doc/library/fnmatch.rst

   1
   2 :mod:`fnmatch` --- Unix filename pattern matching
   3 =================================================
   4
   5 .. module:: fnmatch
   6    :synopsis: Unix shell style filename pattern matching.
   7
   8
   9 .. index:: single: filenames; wildcard expansion
  10
  11 .. index:: module: re
  12
  13 This module provides support for Unix shell-style wildcards, which are *not* the
  14 same as regular expressions (which are documented in the :mod:`re` module).  The
  15 special characters used in shell-style wildcards are:
  16
  17 +------------+------------------------------------+
  18 | Pattern    | Meaning                            |
  19 +============+====================================+
  20 | ``*``      | matches everything                 |
  21 +------------+------------------------------------+
  22 | ``?``      | matches any single character       |
  23 +------------+------------------------------------+
  24 | ``[seq]``  | matches any character in *seq*     |
  25 +------------+------------------------------------+
  26 | ``[!seq]`` | matches any character not in *seq* |
  27 +------------+------------------------------------+
  28
  29 .. index:: module: glob
  30
  31 Note that the filename separator (``'/'`` on Unix) is *not* special to this
  32 module.  See module :mod:`glob` for pathname expansion (:mod:`glob` uses
  33 :func:`fnmatch` to match pathname segments).  Similarly, filenames starting with
  34 a period are not special for this module, and are matched by the ``*`` and ``?``
  35 patterns.
  36
  37
  38 .. function:: fnmatch(filename, pattern)
  39
  40    Test whether the *filename* string matches the *pattern* string, returning
  41    :const:`True` or :const:`False`.  If the operating system is case-insensitive,
  42    then both parameters will be normalized to all lower- or upper-case before
  43    the comparison is performed.  :func:`fnmatchcase` can be used to perform a
  44    case-sensitive comparison, regardless of whether that's standard for the
  45    operating system.
  46
  47    This example will print all file names in the current directory with the
  48    extension ``.txt``::
  49
  50       import fnmatch
  51       import os
  52
  53       for file in os.listdir('.'):
  54           if fnmatch.fnmatch(file, '*.txt'):
  55               print file
  56
  57
  58 .. function:: fnmatchcase(filename, pattern)
  59
  60    Test whether *filename* matches *pattern*, returning :const:`True` or
  61    :const:`False`; the comparison is case-sensitive.
  62
  63
  64 .. function:: filter(names, pattern)
  65
  66    Return the subset of the list of *names* that match *pattern*. It is the same as
  67    ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
  68
  69    .. versionadded:: 2.2
  70
  71
  72 .. function:: translate(pattern)
  73
  74    Return the shell-style *pattern* converted to a regular expression.
  75
  76    Example:
  77
  78       >>> import fnmatch, re
  79       >>>
  80       >>> regex = fnmatch.translate('*.txt')
  81       >>> regex
  82       '.*\\.txt$'
  83       >>> reobj = re.compile(regex)
  84       >>> reobj.match('foobar.txt')
  85       <_sre.SRE_Match object at 0x...>
  86
  87
  88 .. seealso::
  89
  90    Module :mod:`glob`
  91       Unix shell-style path expansion.
  92