• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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(name, pat)
54
55   Test whether the filename string *name* matches the pattern string *pat*,
56   returning ``True`` or ``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(name, pat)
73
74   Test whether the filename string *name* matches the pattern string *pat*,
75   returning ``True`` or ``False``;
76   the comparison is case-sensitive and does not apply :func:`os.path.normcase`.
77
78
79.. function:: filter(names, pat)
80
81   Construct a list from those elements of the :term:`iterable` *names*
82   that match pattern *pat*.
83   It is the same as ``[n for n in names if fnmatch(n, pat)]``,
84   but implemented more efficiently.
85
86
87.. function:: translate(pat)
88
89   Return the shell-style pattern *pat* converted to a regular expression for
90   using with :func:`re.match`.
91
92   Example:
93
94      >>> import fnmatch, re
95      >>>
96      >>> regex = fnmatch.translate('*.txt')
97      >>> regex
98      '(?s:.*\\.txt)\\Z'
99      >>> reobj = re.compile(regex)
100      >>> reobj.match('foobar.txt')
101      <re.Match object; span=(0, 10), match='foobar.txt'>
102
103
104.. seealso::
105
106   Module :mod:`glob`
107      Unix shell-style path expansion.
108