Unix file name pattern matching

Don’t let the name of this function fool you. The fnmatch function is a simple, yet, powerful tool to match any text (not just file names) against a pattern. It is an very easy and powerful way to match text against a pattern, without having to learn regular expressions.

fnmatch(
    self,
    value: str | Iterable[str],
    pattern: str,
    case_sensitive: bool = False,
) -> bool

By default, this function is not case-sensitive. This means that spook and Spook are considered the same. If you want to make the function case-sensitive, set the case_sensitive parameter to True.

Patterns¶

The UNIX shell-style pattern is a relatively simple, easy to learn pattern matching technique, which is not the same as regular expressions.

The following characters are special characters in a pattern:

The sequence of characters in [seq] can be a range, for example: [a-z] or [0-9], or a list of characters, for example: [abc] or [123].

If you want to match any of these special chacters (*, ?, [ or ]) literally, you must wrap them in square brackets ([]), for example: [?].

This is all technical details you need to know about the pattern matching, but let’s look at some examples.

• Pattern spook matches spook.
• Pattern sp*k matches spook, spooook, but also spacewalk, speak, and spank 😅
• Pattern [hb]ook matches hook and book.
• Pattern [!hb]ook matches cook, look (and many more), but not hook or book.
• Pattern t?k matches tik, tok, and character in the second position, but not took.

Hopefully, this gives you a good idea of how to use the pattern matching. In practice, you probably will end up using the * and ? characters the most.

Examples¶

Using fnmatch as a function¶

1
2
{{ fnmatch("Spook", "sp*k") }}
{{ fnmatch("Spook", "spa?k") }}

Returns:

True
False

Using fnmatch as a filter¶

1
2
{{ "Spook" | fnmatch("sp*k") }}
{{ "Spook" | fnmatch("spa?k") }}

Returns:

True
False

Using fnmatch as a test¶

1
2
3
{% if "Spook" is fnmatch("sp*k") %}
  Spook matches!
{% endif %}

Using fnmatch to match a lists of texts¶

You can also pass a list of texts to the fnmatch function. The function will return True if all of the texts in the list matches the pattern. If one of the texts does not match, the function will return False.

1
2
{{ fnmatch(["Spook", "Spook2"], "Sp*") }}
{{ ["Spook", "Ghost"] | fnmatch("Sp*") }}

Returns:

True
False

Case-sensitive matching¶

By default, the fnmatch function is not case-sensitive. This means that spook and Spook are considered the same. If you want to make the function case-sensitive, set the case_sensitive parameter to True.

1
2
{{ fnmatch("Spook", "sp*k", case_sensitive=True) }}
{{ fnmatch("Spook", "sp*k", case_sensitive=False) }}

Returns:

False
True

Features requests, ideas, and support¶

If you have an idea on how to further enhance the Home Assistant template engine, for example, by adding a new template function; feel free to let us know in our discussion forums.

Are you stuck using this new feature? Or maybe you’ve run into a bug? Please check the Support page on where to go for help.