| 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. |