vinegar.utils.system_matcher

Expression matcher for targeting systems. This matcher extends the basic fnmatch pattern syntax with expressions combining several patterns.

A string can be matched against a pattern using the match function. If the same pattern is used repeatedly, a Matcher can be retrieved using the matcher function. However, even the match function implements a simple cache in order to avoid recompiling frequently used patterns.

Pattern expressions understood by this module are combinations of the patterns understood by fnmatch. These combinations can be defined through the use of the logical operators and, not, and or, optionally grouped using parentheses.

Examples:

  • “abc.example.com” exactly matches “abc.example.com”.

  • “*.example.com” matches “abc.example.com” and “123.456.example.com”, but not “abc.example.net”.

  • “*.example.com or *.example.net” matches “abc.example.com” and “123.example.net”, but not “def.example.org”.

  • “*.example.com and not abc.*” matches “def.example.com” and “abc123.example.com”, but not “abc.example.com”.

  • “(*.example.com or *.example.net) and not abc.*” matches “def.example.com” and “def.example.net”, but not “abc.example.com”.

class vinegar.utils.system_matcher.Matcher(pattern: str, case_sensitive: bool)

Matcher object representing a pattern. This is useful when the same pattern is used over-and-over again and has a well-defined life-cycle.

Matcher objects are thread safe.

Instances of this class should be retrieved through the matcher function.

matches(name: str) → bool

Tell whether the specified name matches the pattern.

Parameters

name – name to be matched against the pattern.

vinegar.utils.system_matcher.match(name: str, pattern: str, case_sensitive: bool = False) → bool

Tell whether the specified pattern matches the specified name.

Raises an exception if pattern is not a valid pattern expression supported by this module.

This function internally keeps a cache of compiled patterns in order to reduce the overhead when the same pattern is used repeatedly. Code that knows that such repeatitive behavior will occur should still prefer the matcher function if possible.

Parameters

  • name – name to be matched against pattern.

  • pattern – pattern to be compiled. Please refer to the module documentation for details about the pattern format.

  • case_sensitive – if True, name is treated as case sensitive, otherwise case is ignored.

Returns

True if the pattern matches the name, False otherwise.

vinegar.utils.system_matcher.matcher(pattern: str, case_sensitive: bool = False) → vinegar.utils.system_matcher.Matcher

Return a Matcher for the specified pattern.

Raises an exception if pattern is not a valid pattern expression supported by this module.

This function internally keeps a cache of compiled patterns in order to reduce the overhead when the same pattern is used repeatedly. However, calling code is still encouraged to keep a reference to the returned matcher when it knows that the same pattern is going to be used repeatedly.

Parameters

  • pattern – pattern to be compiled. Please refer to the module documentation for details about the pattern format.

  • case_sensitive – if True, the matcher will be case sensitive, otherwise case is ignored.

Returns

matcher for the specified pattern.