fagus.filters module

This module contains filter-classes used in Fagus

class fagus.filters.FilBase(*filter_args: Any, inexclude: str = '')

Bases: object

FilterBase - base-class for all filters used in Fagus, providing basic functions shared by all filters

__init__(*filter_args: Any, inexclude: str = '') → None

Basic constructor for all filter-classes used in Fagus

Parameters:

• *filter_args – Each argument filters one key in the tree, the last argument filters the leaf-value. You can put a list of values to match different values in the same filter. In this list, you can also specify subfilters to match different grains differently.

• inexclude – In some cases it’s easier to specify that a filter shall match everything except b, rather than match a. ~ can be used to specify for each argument if the filter shall include it (+) or exclude it (-). Valid example: “++-+”. If this parameter isn’t specified, all args will be treated as (+).

included(index: int) → bool

This function returns if the filter should be an include-filter (+) or an exclude-filter (-) at a given index

Parameters:

index – index in filter-arguments that shall be interpreted as include- or exclude-filter

Returns:

bool that is True if it is an include-filter, and False if it is an Exclude-Filter, defaults to True if

undefined at index

match_node(node: Collection[Any], _: Optional[Any] = None) → bool

This method is overridden by CheckFilter and ValueFilter, and otherwise not in use

__annotations__ = {}

__dict__ = mappingproxy({'__module__': 'fagus.filters', '__doc__': 'FilterBase - base-class for all filters used in Fagus, providing basic functions shared by all filters', '__init__': <function FilBase.__init__>, 'included': <function FilBase.included>, 'match_node': <function FilBase.match_node>, '__dict__': <attribute '__dict__' of 'FilBase' objects>, '__weakref__': <attribute '__weakref__' of 'FilBase' objects>, '__annotations__': {}})

__module__ = 'fagus.filters'

__weakref__

list of weak references to the object (if defined)

class fagus.filters.VFil(*filter_args: Any, inexclude: str = '', invert: bool = False)

Bases: FilBase

ValueFilter - This special type of filter can be used to inspect the entire node

It can be used to e.g. select all the nodes that contain at least 10 elements. See README for an example

__init__(*filter_args: Any, inexclude: str = '', invert: bool = False) → None

Parameters:

• *filter_args – Each argument filters one key in the tree, the last argument filters the leaf-value. You can put a list of values to match different values in the same filter. In this list, you can also specify subfilters to match different grains differently.

• inexclude – In some cases it’s easier to specify that a filter shall match everything except b, rather than match a. ~ can be used to specify for each argument if the filter shall include it (+) or exclude it (-). Valid example: “++-+”. If this parameter isn’t specified, all args will be treated as (+).

• invert – Invert this whole filter to match if it doesn’t match. E.g. if you want to select all the nodes that don’t have a certain property.

match_node(node: Collection[Any], _: Optional[Any] = None) → bool

Verify that a node matches ValueFilter

Parameters:

• node – node to check

• _ – this argument is ignored

Returns:

bool whether the filter matched

__annotations__ = {}

__module__ = 'fagus.filters'

class fagus.filters.KFil(*filter_args: Any, inexclude: str = '', str_as_re: bool = False)

Bases: FilBase

KeyFilter - Base class for filters in Fagus that inspect key-values to determine whether the filter matched

__init__(*filter_args: Any, inexclude: str = '', str_as_re: bool = False) → None

Initializes KeyFilter and verifies the arguments passed to it

Parameters:

• *filter_args – Each argument filters one key in the tree, the last argument filters the leaf-value. You can put a list of values to match different values in the same filter. In this list, you can also specify subfilters to match different grains differently.

• inexclude – In some cases it’s easier to specify that a filter shall match everything except b, rather than match a. ~ can be used to specify for each argument if the filter shall include it (+) or exclude it (-). Valid example: “++-+”. If this parameter isn’t specified, all args will be treated as (+).

• str_as_re – If this is set to True, it will be evaluated for all str’s if they’d match differently as a regex, and in the latter case match these strings as regex patterns. E.g. re.match(“a.*”, b) will match differently than “a.*” == b. In this case, “a.*” will be used as a regex-pattern. However re.match(“abc”, b) will give the same result as “abc” == b, so here “abc” == b will be used.

Raises:

TypeError – if the filters are not stacked correctly / stacked in a way that doesn’t make sense

__getitem__(index: int) → Any

Get filter-argument at index

Returns:

filter-argument at index, _None if index isn’t defined

__setitem__(key: int, value: Any) → None

Set filter-argument at index. Throws IndexError if that index isn’t defined

match(value: Any, index: int = 0, _: Optional[Any] = None) → Tuple[bool, Optional[KFil], int]

match filter at index (matches recursively into subfilters if necessary)

Parameters:

• value – the value to be matched against the filter

• index – index of filter-argument to check

• _ – this argument is ignored

Returns:

whether the value matched the filter, the filter that matched (as it can be a subfilter), and the next index

in that (sub)filter

match_list(value: int, index: int = 0, node_length: int = 0) → Tuple[bool, Optional[KFil], int]

match_list: same as match, but optimized to match list-indices (e. g. no regex-matching here)

Parameters:

• value – the value to be matched against the filter

• index – index of filter-argument to check

• node_length – length of the list whose indices shall be verified

Returns:

whether the value matched the filter, the filter that matched (as it can be a subfilter), and the next index

in that (sub)filter

match_extra_filters(node: Collection[Any], index: int = 0) → bool

Match extra filters on node (CFil and VFil).

Parameters:

• node – node to be verified

• index – filter_index to check for extra filters

Returns:

bool whether the extra filters matched

__annotations__ = {}

__module__ = 'fagus.filters'

class fagus.filters.Fil(*filter_args: Any, inexclude: str = '', str_as_re: bool = False)

Bases: KFil

TFilter - what matches this filter will actually be visible in the result. See README

__annotations__ = {}

__module__ = 'fagus.filters'

class fagus.filters.CFil(*filter_args: Any, inexclude: str = '', str_as_re: bool = False, invert: bool = False)

Bases: KFil

CFil - can be used to select nodes based on values that shall not appear in the result. See README

__init__(*filter_args: Any, inexclude: str = '', str_as_re: bool = False, invert: bool = False) → None

Initializes KeyFilter and verifies the arguments passed to it

Parameters:

• *filter_args – Each argument filters one key in the tree, the last argument filters the leaf-value. You can put a list of values to match different values in the same filter. In this list, you can also specify subfilters to match different grains differently.

• inexclude – In some cases it’s easier to specify that a filter shall match everything except b, rather than match a. ~ can be used to specify for each argument if the filter shall include it (+) or exclude it (-). Valid example: “++-+”. If this parameter isn’t specified, all args will be treated as (+).

• str_as_re – If this is set to True, it will be evaluated for all str’s if they’d match differently as a regex, and in the latter case match these strings as regex patterns. E.g. re.match(“a.*”, b) will match differently than “a.*” == b. In this case, “a.*” will be used as a regex-pattern. However re.match(“abc”, b) will give the same result as “abc” == b, so here “abc” == b will be used.

Raises:

TypeError – if the filters are not stacked correctly, or stacked in a way that doesn’t make sense

match_node(node: Collection[Any], index: int = 0) → bool

Recursive function to completely verify a node and its subnodes in CFil

Parameters:

• node – node to check

• index – index in filter to check (filter is self)

Returns:

bool whether the filter matched

__annotations__ = {}

__module__ = 'fagus.filters'