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