/Doc/library/fnmatch.rst

 1
 2:mod:`fnmatch` --- Unix filename pattern matching
 3=================================================
 4
 5.. module:: fnmatch
 6   :synopsis: Unix shell style filename pattern matching.
 7
 8
 9.. index:: single: filenames; wildcard expansion
10
11.. index:: module: re
12
13This module provides support for Unix shell-style wildcards, which are *not* the
14same as regular expressions (which are documented in the :mod:`re` module).  The
15special characters used in shell-style wildcards are:
16
17+------------+------------------------------------+
18| Pattern    | Meaning                            |
19+============+====================================+
20| ``*``      | matches everything                 |
21+------------+------------------------------------+
22| ``?``      | matches any single character       |
23+------------+------------------------------------+
24| ``[seq]``  | matches any character in *seq*     |
25+------------+------------------------------------+
26| ``[!seq]`` | matches any character not in *seq* |
27+------------+------------------------------------+
28
29.. index:: module: glob
30
31Note that the filename separator (``'/'`` on Unix) is *not* special to this
32module.  See module :mod:`glob` for pathname expansion (:mod:`glob` uses
33:func:`fnmatch` to match pathname segments).  Similarly, filenames starting with
34a period are not special for this module, and are matched by the ``*`` and ``?``
35patterns.
36
37
38.. function:: fnmatch(filename, pattern)
39
40   Test whether the *filename* string matches the *pattern* string, returning
41   :const:`True` or :const:`False`.  If the operating system is case-insensitive,
42   then both parameters will be normalized to all lower- or upper-case before
43   the comparison is performed.  :func:`fnmatchcase` can be used to perform a
44   case-sensitive comparison, regardless of whether that's standard for the
45   operating system.
46
47   This example will print all file names in the current directory with the
48   extension ``.txt``::
49
50      import fnmatch
51      import os
52
53      for file in os.listdir('.'):
54          if fnmatch.fnmatch(file, '*.txt'):
55              print file
56
57
58.. function:: fnmatchcase(filename, pattern)
59
60   Test whether *filename* matches *pattern*, returning :const:`True` or
61   :const:`False`; the comparison is case-sensitive.
62
63
64.. function:: filter(names, pattern)
65
66   Return the subset of the list of *names* that match *pattern*. It is the same as
67   ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
68
69   .. versionadded:: 2.2
70
71
72.. function:: translate(pattern)
73
74   Return the shell-style *pattern* converted to a regular expression.
75
76   Example:
77
78      >>> import fnmatch, re
79      >>>
80      >>> regex = fnmatch.translate('*.txt')
81      >>> regex
82      '.*\\.txt$'
83      >>> reobj = re.compile(regex)
84      >>> reobj.match('foobar.txt')
85      <_sre.SRE_Match object at 0x...>
86
87
88.. seealso::
89
90   Module :mod:`glob`
91      Unix shell-style path expansion.
92