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 true
  41    or false.  If the operating system is case-insensitive, then both parameters
  42    will be normalized to all lower- or upper-case before the comparison is
  43    performed.  If you require a case-sensitive comparison regardless of whether
  44    that's standard for your operating system, use :func:`fnmatchcase` instead.
  45
  46    This example will print all file names in the current directory with the
  47    extension ``.txt``::
  48
  49       import fnmatch
  50       import os
  51
  52       for file in os.listdir('.'):
  53           if fnmatch.fnmatch(file, '*.txt'):
  54               print file
  55
  56
  57 .. function:: fnmatchcase(filename, pattern)
  58
  59    Test whether *filename* matches *pattern*, returning true or false; the
  60    comparison is case-sensitive.
  61
  62
  63 .. function:: filter(names, pattern)
  64
  65    Return the subset of the list of *names* that match *pattern*. It is the same as
  66    ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
  67
  68    .. versionadded:: 2.2
  69
  70
  71 .. function:: translate(pattern)
  72
  73    Return the shell-style *pattern* converted to a regular expression.
  74
  75    Example::
  76
  77       >>> import fnmatch, re
  78       >>>
  79       >>> regex = fnmatch.translate('*.txt')
  80       >>> regex
  81       '.*\\.txt$'
  82       >>> reobj = re.compile(regex)
  83       >>> print reobj.match('foobar.txt')
  84       <_sre.SRE_Match object at 0x...>
  85
  86
  87 .. seealso::
  88
  89    Module :mod:`glob`
  90       Unix shell-style path expansion.
  91