Debian Codegraph @

Doc/library/fnmatch.rst

raw
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
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:: pair: 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 Unless stated otherwise, "filename string" and "pattern string" either refer to
50 :class:`str` or ``ISO-8859-1`` encoded :class:`bytes` objects. Note that the
51 functions documented below do not allow to mix a :class:`!bytes` pattern with
52 a :class:`!str` filename, and vice-versa.
53
54 Finally, note that :func:`functools.lru_cache` with a *maxsize* of 32768
55 is used to cache the (typed) compiled regex patterns in the following
56 functions: :func:`fnmatch`, :func:`fnmatchcase`, :func:`.filter`, :func:`.filterfalse`.
57
58
59 .. function:: fnmatch(name, pat)
60
61 Test whether the filename string *name* matches the pattern string *pat*,
62 returning ``True`` or ``False``. Both parameters are case-normalized
63 using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a
64 case-sensitive comparison, regardless of whether that's standard for the
65 operating system.
66
67 This example will print all file names in the current directory with the
68 extension ``.txt``::
69
70 import fnmatch
71 import os
72
73 for file in os.listdir('.'):
74 if fnmatch.fnmatch(file, '*.txt'):
75 print(file)
76
77
78 .. function:: fnmatchcase(name, pat)
79
80 Test whether the filename string *name* matches the pattern string *pat*,
81 returning ``True`` or ``False``;
82 the comparison is case-sensitive and does not apply :func:`os.path.normcase`.
83
84
85 .. function:: filter(names, pat)
86
87 Construct a list from those elements of the :term:`iterable` of filename
88 strings *names* that match the pattern string *pat*.
89 It is the same as ``[n for n in names if fnmatch(n, pat)]``,
90 but implemented more efficiently.
91
92
93 .. function:: filterfalse(names, pat)
94
95 Construct a list from those elements of the :term:`iterable` of filename
96 strings *names* that do not match the pattern string *pat*.
97 It is the same as ``[n for n in names if not fnmatch(n, pat)]``,
98 but implemented more efficiently.
99
100 .. versionadded:: 3.14
101
102
103 .. function:: translate(pat)
104
105 Return the shell-style pattern *pat* converted to a regular expression for
106 using with :func:`re.match`. The pattern is expected to be a :class:`str`.
107
108 Example:
109
110 >>> import fnmatch, re
111 >>>
112 >>> regex = fnmatch.translate('*.txt')
113 >>> regex
114 '(?s:.*\\.txt)\\z'
115 >>> reobj = re.compile(regex)
116 >>> reobj.match('foobar.txt')
117 <re.Match object; span=(0, 10), match='foobar.txt'>
118
119
120 .. seealso::
121
122 Module :mod:`glob`
123 Unix shell-style path expansion.