Unix file name pattern filtering - Spook 👻 a scary powerful toolbox for Home Assistant.

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

Template function properties
Function	Filter a lists of texts against a pattern
Function name	`fnmatch_filter`
Returns	The filtered list
Return type	list of strings
Can be used as a filter	Yes
Can be used as a test	No
Spook's influence	Newly added template function
Developer tools	Try this in the template developer tools

Signature
`fnmatch_filter( self, value: Iterable[str], pattern: str, case_sensitive: bool = False, ) -> List[str]`

Function parameters
Attribute	Type	Required	Default / Example
`value`	list of strings	Yes	`["Spook", "Ghost"]`
`pattern`	string	Yes	`sp*k`
`case_sensitive`	list of strings	No	`False`

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:

Character	Meaning
`*`	Matches everything (and multiple characters)
`?`	Matches any single character
`[seq]`	Matches any character present in this sequence
`[!seq]`	Matches any character not present in this sequence

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 filter as a function¶

1
2
{{ fnmatch_filter(["Spook", "Ghost", "Spacewalk"], "sp*k") }}
{{ fnmatch_filter(["Spook", "Ghost", "Spank"], "spa?k") }}

Returns:

["Spook", "Spacewalk"]
["Spank"]

Using fnmatch filter as a filter¶

1
2
{{ ["Spook", "Ghost", "Spacewalk"] | fnmatch_filter("sp*k") }}
{{ ["Spook", "Ghost", "Spank"] | fnmatch_filter("spa?k") }}

Returns:

["Spook", "Spacewalk"]
["Spank"]

Case-sensitive matching¶

By default, the fnmatch_filter 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_filter(["Spook", "spook"], "sp*k", case_sensitive=True) }}
{{ fnmatch_filter(["Spook", "spook"], case_sensitive=False) }}

Returns:

["spook"]
["Spook", "spook"]

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.