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 .. index::
     20    single: * (asterisk); in glob-style wildcards
     21    single: ? (question mark); in glob-style wildcards
     22    single: [] (square brackets); in glob-style wildcards
     23    single: ! (exclamation); in glob-style wildcards
     24    single: - (minus); in glob-style wildcards
     25 
     26 +------------+------------------------------------+
     27 | Pattern    | Meaning                            |
     28 +============+====================================+
     29 | ``*``      | matches everything                 |
     30 +------------+------------------------------------+
     31 | ``?``      | matches any single character       |
     32 +------------+------------------------------------+
     33 | ``[seq]``  | matches any character in *seq*     |
     34 +------------+------------------------------------+
     35 | ``[!seq]`` | matches any character not in *seq* |
     36 +------------+------------------------------------+
     37 
     38 For a literal match, wrap the meta-characters in brackets.
     39 For example, ``'[?]'`` matches the character ``'?'``.
     40 
     41 .. index:: module: glob
     42 
     43 Note that the filename separator (``'/'`` on Unix) is *not* special to this
     44 module.  See module :mod:`glob` for pathname expansion (:mod:`glob` uses
     45 :func:`.filter` to match pathname segments).  Similarly, filenames starting with
     46 a period are not special for this module, and are matched by the ``*`` and ``?``
     47 patterns.
     48 
     49 
     50 .. function:: fnmatch(filename, pattern)
     51 
     52    Test whether the *filename* string matches the *pattern* string, returning
     53    :const:`True` or :const:`False`.  Both parameters are case-normalized
     54    using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a
     55    case-sensitive comparison, regardless of whether that's standard for the
     56    operating system.
     57 
     58    This example will print all file names in the current directory with the
     59    extension ``.txt``::
     60 
     61       import fnmatch
     62       import os
     63 
     64       for file in os.listdir('.'):
     65           if fnmatch.fnmatch(file, '*.txt'):
     66               print(file)
     67 
     68 
     69 .. function:: fnmatchcase(filename, pattern)
     70 
     71    Test whether *filename* matches *pattern*, returning :const:`True` or
     72    :const:`False`; the comparison is case-sensitive and does not apply
     73    :func:`os.path.normcase`.
     74 
     75 
     76 .. function:: filter(names, pattern)
     77 
     78    Return the subset of the list of *names* that match *pattern*. It is the same as
     79    ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
     80 
     81 
     82 .. function:: translate(pattern)
     83 
     84    Return the shell-style *pattern* converted to a regular expression for
     85    using with :func:`re.match`.
     86 
     87    Example:
     88 
     89       >>> import fnmatch, re
     90       >>>
     91       >>> regex = fnmatch.translate('*.txt')
     92       >>> regex
     93       '(?s:.*\\.txt)\\Z'
     94       >>> reobj = re.compile(regex)
     95       >>> reobj.match('foobar.txt')
     96       <re.Match object; span=(0, 10), match='foobar.txt'>
     97 
     98 
     99 .. seealso::
    100 
    101    Module :mod:`glob`
    102       Unix shell-style path expansion.
    103