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
15This module provides support for Unix shell-style wildcards, which are *not* the
16same as regular expressions (which are documented in the :mod:`re` module).  The
17special 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
38For a literal match, wrap the meta-characters in brackets.
39For example, ``'[?]'`` matches the character ``'?'``.
40
41.. index:: module: glob
42
43Note that the filename separator (``'/'`` on Unix) is *not* special to this
44module.  See module :mod:`glob` for pathname expansion (:mod:`glob` uses
45:func:`.filter` to match pathname segments).  Similarly, filenames starting with
46a period are not special for this module, and are matched by the ``*`` and ``?``
47patterns.
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   Construct a list from those elements of the iterable *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