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