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:: pair: 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:: pair: 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
49Also note that :func:`functools.lru_cache` with the *maxsize* of 32768 is used to
50cache the compiled regex patterns in the following functions: :func:`fnmatch`,
51:func:`fnmatchcase`, :func:`.filter`.
52
53.. function:: fnmatch(filename, pattern)
54
55   Test whether the *filename* string matches the *pattern* string, returning
56   :const:`True` or :const:`False`.  Both parameters are case-normalized
57   using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a
58   case-sensitive comparison, regardless of whether that's standard for the
59   operating system.
60
61   This example will print all file names in the current directory with the
62   extension ``.txt``::
63
64      import fnmatch
65      import os
66
67      for file in os.listdir('.'):
68          if fnmatch.fnmatch(file, '*.txt'):
69              print(file)
70
71
72.. function:: fnmatchcase(filename, pattern)
73
74   Test whether *filename* matches *pattern*, returning :const:`True` or
75   :const:`False`; the comparison is case-sensitive and does not apply
76   :func:`os.path.normcase`.
77
78
79.. function:: filter(names, pattern)
80
81   Construct a list from those elements of the iterable *names* that match *pattern*. It is the same as
82   ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
83
84
85.. function:: translate(pattern)
86
87   Return the shell-style *pattern* converted to a regular expression for
88   using with :func:`re.match`.
89
90   Example:
91
92      >>> import fnmatch, re
93      >>>
94      >>> regex = fnmatch.translate('*.txt')
95      >>> regex
96      '(?s:.*\\.txt)\\Z'
97      >>> reobj = re.compile(regex)
98      >>> reobj.match('foobar.txt')
99      <re.Match object; span=(0, 10), match='foobar.txt'>
100
101
102.. seealso::
103
104   Module :mod:`glob`
105      Unix shell-style path expansion.
106