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`.  If the operating system is case-insensitive,
     48    then both parameters will be normalized to all lower- or upper-case before
     49    the comparison is performed.  :func:`fnmatchcase` can be used to perform a
     50    case-sensitive comparison, regardless of whether that's standard for the
     51    operating system.
     52 
     53    This example will print all file names in the current directory with the
     54    extension ``.txt``::
     55 
     56       import fnmatch
     57       import os
     58 
     59       for file in os.listdir('.'):
     60           if fnmatch.fnmatch(file, '*.txt'):
     61               print file
     62 
     63 
     64 .. function:: fnmatchcase(filename, pattern)
     65 
     66    Test whether *filename* matches *pattern*, returning :const:`True` or
     67    :const:`False`; the comparison is case-sensitive.
     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