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
16This module provides support for Unix shell-style wildcards, which are *not* the
17same as regular expressions (which are documented in the :mod:`re` module).  The
18special 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
32For a literal match, wrap the meta-characters in brackets.
33For example, ``'[?]'`` matches the character ``'?'``.
34
35.. index:: module: glob
36
37Note that the filename separator (``'/'`` on Unix) is *not* special to this
38module.  See module :mod:`glob` for pathname expansion (:mod:`glob` uses
39:func:`fnmatch` to match pathname segments).  Similarly, filenames starting with
40a period are not special for this module, and are matched by the ``*`` and ``?``
41patterns.
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