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 **Source code:** :source:`Lib/fnmatch.py`
      8 
      9 .. index:: single: filenames; wildcard expansion
     10 
     11 .. index:: module: re
     12 
     13 --------------
     14 
     15 This module provides support for Unix shell-style wildcards, which are *not* the
     16 same as regular expressions (which are documented in the :mod:`re` module).  The
     17 special characters used in shell-style wildcards are:
     18 
     19 +------------+------------------------------------+
     20 | Pattern    | Meaning                            |
     21 +============+====================================+
     22 | ``*``      | matches everything                 |
     23 +------------+------------------------------------+
     24 | ``?``      | matches any single character       |
     25 +------------+------------------------------------+
     26 | ``[seq]``  | matches any character in *seq*     |
     27 +------------+------------------------------------+
     28 | ``[!seq]`` | matches any character not in *seq* |
     29 +------------+------------------------------------+
     30 
     31 For a literal match, wrap the meta-characters in brackets.
     32 For example, ``'[?]'`` matches the character ``'?'``.
     33 
     34 .. index:: module: glob
     35 
     36 Note that the filename separator (``'/'`` on Unix) is *not* special to this
     37 module.  See module :mod:`glob` for pathname expansion (:mod:`glob` uses
     38 :func:`fnmatch` to match pathname segments).  Similarly, filenames starting with
     39 a period are not special for this module, and are matched by the ``*`` and ``?``
     40 patterns.
     41 
     42 
     43 .. function:: fnmatch(filename, pattern)
     44 
     45    Test whether the *filename* string matches the *pattern* string, returning
     46    :const:`True` or :const:`False`.  If the operating system is case-insensitive,
     47    then both parameters will be normalized to all lower- or upper-case before
     48    the comparison is performed.  :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.
     67 
     68 
     69 .. function:: filter(names, pattern)
     70 
     71    Return the subset of the list of *names* that match *pattern*. It is the same as
     72    ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
     73 
     74 
     75 .. function:: translate(pattern)
     76 
     77    Return the shell-style *pattern* converted to a regular expression for
     78    using with :func:`re.match`.
     79 
     80    Example:
     81 
     82       >>> import fnmatch, re
     83       >>>
     84       >>> regex = fnmatch.translate('*.txt')
     85       >>> regex
     86       '(?s:.*\\.txt)\\Z'
     87       >>> reobj = re.compile(regex)
     88       >>> reobj.match('foobar.txt')
     89       <_sre.SRE_Match object; span=(0, 10), match='foobar.txt'>
     90 
     91 
     92 .. seealso::
     93 
     94    Module :mod:`glob`
     95       Unix shell-style path expansion.
     96